logstack-js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mosesedem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# logstack-js
+
+The JavaScript/TypeScript SDK for [Logstack](https://github.com/Mosesedem/logstack) — log
+ingestion, real-time streaming, and querying.
+
+## Installation
+
+```bash
+npm install logstack-js
+# or: pnpm add logstack-js / yarn add logstack-js
+```
+
+## Quick start
+
+```ts
+import { createLogStack } from "logstack-js";
+
+const logstack = createLogStack({
+  apiKey: "ls_live_xxx",
+  // endpoint host (SDK appends /v1/logs); defaults to https://api.logstack.tech
+  // endpoint: "http://localhost:8080",
+});
+
+logstack.info("Application started", { version: "1.0.0" });
+logstack.error("Payment failed", { orderId: "ord_123", code: 402 });
+
+// flush + stop timers on shutdown
+await logstack.close();
+```
+
+## Behavior
+
+- **Console and server are independent.** Every log is written to the console (always in
+  development/test; in production only when `consoleInProduction: true`, unless `silent`),
+  and is *also* shipped to the server whenever an `apiKey` is set and `disabled` is false —
+  in **all** environments.
+- A missing API key should degrade the client to console-only (`disabled: true`); it must
+  never become a silent no-op.
+- Browser logs are queued to `localStorage` while offline (bounded by `maxOfflineQueueSize`,
+  default 1000) and flushed on reconnect.
+
+## Configuration
+
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `apiKey` | — | **Required.** Project API key (`ls_...`). |
+| `endpoint` | `https://api.logstack.tech` | API host; the SDK appends `/v1/logs`. |
+| `environment` | auto (`NODE_ENV`) | `development` \| `staging` \| `production` \| `test`. |
+| `batchSize` | `100` | Logs buffered before an auto-flush. |
+| `flushInterval` | `5000` | Auto-flush interval (ms). |
+| `maxRetries` | `3` | Retry attempts for `5xx` responses. |
+| `consoleInProduction` | `false` | Also log to console in production/staging. |
+| `silent` | `false` | Disable all console output. |
+| `disabled` | `false` | Console-only mode: never buffer, send, or queue. |
+| `maxOfflineQueueSize` | `1000` | Cap on the offline (localStorage) queue. |
+| `captureContext` | `true` | Auto-capture URL/route/user-agent in the browser. |
+| `onError` | — | `(error, logs) => void` callback for send failures. |
+
+## Log levels
+
+`debug` · `info` · `warn` · `error` · `critical` · `fatal` — each available as a method, e.g.
+`logstack.debug(message, metadata?)`.
+
+## Querying
+
+With `projectId` in the config you can read logs back:
+
+```ts
+const result = await logstack.getLogs({ level: "error", limit: 50 });
+const one = await logstack.getLogById(12345);
+```
+
+Full reference: [docs/SDK.md](https://github.com/Mosesedem/logstack/blob/main/docs/SDK.md).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,132 @@
+type LogLevel = "debug" | "info" | "warn" | "error" | "critical" | "fatal";
+type Environment = "development" | "production" | "staging" | "test";
+interface LogContext {
+    /** Page URL or API endpoint where the log originated */
+    url?: string;
+    /** Route path (for framework routing) */
+    route?: string;
+    /** HTTP method (for API endpoints) */
+    method?: string;
+    /** User agent string */
+    userAgent?: string;
+    /** Client IP address */
+    ip?: string;
+    /** Request ID for tracing */
+    requestId?: string;
+    /** Component or module name */
+    component?: string;
+}
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+    timestamp?: string;
+    /** Contextual information about where the log originated */
+    context?: LogContext;
+}
+interface LogRecord extends LogEntry {
+    id: number;
+    projectId: string;
+    createdAt: string;
+}
+interface LogQueryOptions {
+    /** Filter by log level */
+    level?: LogLevel;
+    /** Search in message content */
+    search?: string;
+    /** Start time for date range filter (ISO 8601) */
+    startTime?: string;
+    /** End time for date range filter (ISO 8601) */
+    endTime?: string;
+    /** Number of records to skip */
+    offset?: number;
+    /** Maximum number of records to return (max 1000) */
+    limit?: number;
+}
+interface LogQueryResult {
+    logs: LogRecord[];
+    total: number;
+    offset: number;
+    limit: number;
+}
+interface LogStackConfig {
+    apiKey: string;
+    endpoint?: string;
+    batchSize?: number;
+    flushInterval?: number;
+    maxRetries?: number;
+    onError?: (error: Error, logs: LogEntry[]) => void;
+    /**
+     * Environment label attached to logs and used for console gating (see
+     * `consoleInProduction`). Logs are sent to the server in every environment as
+     * long as an `apiKey` is set and `disabled` is not true. Auto-detected from
+     * `NODE_ENV` when omitted; defaults to 'production'.
+     */
+    environment?: Environment;
+    /**
+     * Whether to log to the console in production/staging mode. In development and
+     * test, console output is always on (unless `silent`). Defaults to false, so
+     * production stays quiet on the console while still shipping logs to the server.
+     */
+    consoleInProduction?: boolean;
+    /**
+     * Disable all console output regardless of environment. Defaults to false.
+     */
+    silent?: boolean;
+    /**
+     * Console-only mode: log to the console but never buffer, send, or queue to the
+     * server. Use when no API key/endpoint is available (e.g. local dev without a
+     * configured project). Defaults to false.
+     */
+    disabled?: boolean;
+    /**
+     * Maximum number of logs retained in the offline (localStorage) queue. Oldest
+     * entries are dropped past this cap to avoid exceeding storage quota.
+     * Defaults to 1000.
+     */
+    maxOfflineQueueSize?: number;
+    /**
+     * Auto-capture context like URL, route, user agent.
+     * Defaults to true.
+     */
+    captureContext?: boolean;
+    /**
+     * Project ID for query operations. Required for getLogs/getLogById.
+     */
+    projectId?: string;
+}
+interface LogStackClient {
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+    critical(message: string, metadata?: Record<string, unknown>): void;
+    fatal(message: string, metadata?: Record<string, unknown>): void;
+    log(entry: LogEntry): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    /** Set context that will be included with all subsequent logs */
+    setContext(context: LogContext): void;
+    /** Clear the current context */
+    clearContext(): void;
+    /** Query logs from the server (requires projectId in config) */
+    getLogs(options?: LogQueryOptions): Promise<LogQueryResult>;
+    /** Get a single log by ID (requires projectId in config) */
+    getLogById(logId: number): Promise<LogRecord>;
+}
+/** Structured error from Logstack API */
+interface LogStackErrorResponse {
+    code: string;
+    message: string;
+}
+/** Error class for Logstack API errors */
+declare class LogStackError extends Error {
+    code: string;
+    status: number;
+    constructor(code: string, message: string, status: number);
+}
+
+declare function createLogStack(config: LogStackConfig): LogStackClient;
+
+export { type Environment, type LogContext, type LogEntry, type LogLevel, type LogQueryOptions, type LogQueryResult, type LogRecord, type LogStackClient, type LogStackConfig, LogStackError, type LogStackErrorResponse, createLogStack };

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+type LogLevel = "debug" | "info" | "warn" | "error" | "critical" | "fatal";
+type Environment = "development" | "production" | "staging" | "test";
+interface LogContext {
+    /** Page URL or API endpoint where the log originated */
+    url?: string;
+    /** Route path (for framework routing) */
+    route?: string;
+    /** HTTP method (for API endpoints) */
+    method?: string;
+    /** User agent string */
+    userAgent?: string;
+    /** Client IP address */
+    ip?: string;
+    /** Request ID for tracing */
+    requestId?: string;
+    /** Component or module name */
+    component?: string;
+}
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+    timestamp?: string;
+    /** Contextual information about where the log originated */
+    context?: LogContext;
+}
+interface LogRecord extends LogEntry {
+    id: number;
+    projectId: string;
+    createdAt: string;
+}
+interface LogQueryOptions {
+    /** Filter by log level */
+    level?: LogLevel;
+    /** Search in message content */
+    search?: string;
+    /** Start time for date range filter (ISO 8601) */
+    startTime?: string;
+    /** End time for date range filter (ISO 8601) */
+    endTime?: string;
+    /** Number of records to skip */
+    offset?: number;
+    /** Maximum number of records to return (max 1000) */
+    limit?: number;
+}
+interface LogQueryResult {
+    logs: LogRecord[];
+    total: number;
+    offset: number;
+    limit: number;
+}
+interface LogStackConfig {
+    apiKey: string;
+    endpoint?: string;
+    batchSize?: number;
+    flushInterval?: number;
+    maxRetries?: number;
+    onError?: (error: Error, logs: LogEntry[]) => void;
+    /**
+     * Environment label attached to logs and used for console gating (see
+     * `consoleInProduction`). Logs are sent to the server in every environment as
+     * long as an `apiKey` is set and `disabled` is not true. Auto-detected from
+     * `NODE_ENV` when omitted; defaults to 'production'.
+     */
+    environment?: Environment;
+    /**
+     * Whether to log to the console in production/staging mode. In development and
+     * test, console output is always on (unless `silent`). Defaults to false, so
+     * production stays quiet on the console while still shipping logs to the server.
+     */
+    consoleInProduction?: boolean;
+    /**
+     * Disable all console output regardless of environment. Defaults to false.
+     */
+    silent?: boolean;
+    /**
+     * Console-only mode: log to the console but never buffer, send, or queue to the
+     * server. Use when no API key/endpoint is available (e.g. local dev without a
+     * configured project). Defaults to false.
+     */
+    disabled?: boolean;
+    /**
+     * Maximum number of logs retained in the offline (localStorage) queue. Oldest
+     * entries are dropped past this cap to avoid exceeding storage quota.
+     * Defaults to 1000.
+     */
+    maxOfflineQueueSize?: number;
+    /**
+     * Auto-capture context like URL, route, user agent.
+     * Defaults to true.
+     */
+    captureContext?: boolean;
+    /**
+     * Project ID for query operations. Required for getLogs/getLogById.
+     */
+    projectId?: string;
+}
+interface LogStackClient {
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+    critical(message: string, metadata?: Record<string, unknown>): void;
+    fatal(message: string, metadata?: Record<string, unknown>): void;
+    log(entry: LogEntry): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    /** Set context that will be included with all subsequent logs */
+    setContext(context: LogContext): void;
+    /** Clear the current context */
+    clearContext(): void;
+    /** Query logs from the server (requires projectId in config) */
+    getLogs(options?: LogQueryOptions): Promise<LogQueryResult>;
+    /** Get a single log by ID (requires projectId in config) */
+    getLogById(logId: number): Promise<LogRecord>;
+}
+/** Structured error from Logstack API */
+interface LogStackErrorResponse {
+    code: string;
+    message: string;
+}
+/** Error class for Logstack API errors */
+declare class LogStackError extends Error {
+    code: string;
+    status: number;
+    constructor(code: string, message: string, status: number);
+}
+
+declare function createLogStack(config: LogStackConfig): LogStackClient;
+
+export { type Environment, type LogContext, type LogEntry, type LogLevel, type LogQueryOptions, type LogQueryResult, type LogRecord, type LogStackClient, type LogStackConfig, LogStackError, type LogStackErrorResponse, createLogStack };

package/dist/index.js

@@ -0,0 +1,505 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LogStackError: () => LogStackError,
+  createLogStack: () => createLogStack
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var LogStackError = class extends Error {
+  constructor(code, message, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "LogStackError";
+  }
+};
+
+// src/index.ts
+var DEFAULT_ENDPOINT = "https://api.logstack.tech";
+var DEFAULT_BATCH_SIZE = 100;
+var DEFAULT_FLUSH_INTERVAL = 5e3;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_MAX_OFFLINE_QUEUE = 1e3;
+var RETRY_BASE_DELAY = 1e3;
+var OFFLINE_STORAGE_KEY = "logstack_offline_queue";
+var OFFLINE_STORAGE_TTL = 24 * 60 * 60 * 1e3;
+var LEVEL_COLORS = {
+  debug: "\x1B[35m",
+  // Magenta
+  info: "\x1B[36m",
+  // Cyan
+  warn: "\x1B[33m",
+  // Yellow
+  error: "\x1B[31m",
+  // Red
+  critical: "\x1B[41m\x1B[37m",
+  // White on Red background
+  fatal: "\x1B[45m\x1B[37m"
+  // White on Magenta background
+};
+var RESET_COLOR = "\x1B[0m";
+var BROWSER_STYLES = {
+  debug: "color: #a371f7; font-weight: bold",
+  info: "color: #58a6ff; font-weight: bold",
+  warn: "color: #d29922; font-weight: bold",
+  error: "color: #f85149; font-weight: bold",
+  critical: "background: #da3633; color: white; font-weight: bold; padding: 2px 6px; border-radius: 2px",
+  fatal: "background: #8957e5; color: white; font-weight: bold; padding: 2px 6px; border-radius: 2px"
+};
+function isBrowserEnvironment() {
+  return typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
+}
+function getBrowserWindow() {
+  if (!isBrowserEnvironment()) {
+    return void 0;
+  }
+  const win = globalThis.window;
+  if (typeof win !== "object" || win === null) {
+    return void 0;
+  }
+  return win;
+}
+function getBrowserStorage() {
+  if (!isBrowserEnvironment()) {
+    return void 0;
+  }
+  const storage = globalThis.localStorage;
+  if (typeof storage !== "object" || storage === null) {
+    return void 0;
+  }
+  return storage;
+}
+function getBrowserContext() {
+  const win = getBrowserWindow();
+  if (!win) {
+    return {};
+  }
+  return {
+    url: win.location?.href,
+    route: win.location?.pathname,
+    userAgent: win.navigator?.userAgent
+  };
+}
+var LogStack = class {
+  constructor(config) {
+    this.buffer = [];
+    this.flushTimer = null;
+    this.isFlushing = false;
+    this.isClosing = false;
+    this.globalContext = {};
+    this.isOnline = true;
+    this.offlineQueue = [];
+    this.offlineRetryTimer = null;
+    this.isBrowser = isBrowserEnvironment();
+    const detectedEnvironment = this.detectEnvironment();
+    this.config = {
+      apiKey: config.apiKey,
+      endpoint: config.endpoint || DEFAULT_ENDPOINT,
+      batchSize: config.batchSize || DEFAULT_BATCH_SIZE,
+      flushInterval: config.flushInterval || DEFAULT_FLUSH_INTERVAL,
+      maxRetries: config.maxRetries || DEFAULT_MAX_RETRIES,
+      environment: config.environment || detectedEnvironment,
+      consoleInProduction: config.consoleInProduction || false,
+      silent: config.silent || false,
+      disabled: config.disabled || false,
+      maxOfflineQueueSize: config.maxOfflineQueueSize ?? DEFAULT_MAX_OFFLINE_QUEUE,
+      captureContext: config.captureContext !== false,
+      onError: config.onError,
+      projectId: config.projectId
+    };
+    if (!this.config.disabled) {
+      this.startFlushTimer();
+    }
+    if (this.config.captureContext && this.isBrowser) {
+      this.captureDefaultContext();
+    }
+    if (this.isBrowser && !this.config.disabled) {
+      this.setupOfflineDetection();
+      this.restoreOfflineQueue();
+    }
+  }
+  detectEnvironment() {
+    if (typeof process !== "undefined" && process.env) {
+      const nodeEnv = process.env.NODE_ENV;
+      if (nodeEnv === "development" || nodeEnv === "dev") return "development";
+      if (nodeEnv === "test") return "test";
+      if (nodeEnv === "staging") return "staging";
+    }
+    return "production";
+  }
+  setupOfflineDetection() {
+    const win = getBrowserWindow();
+    if (!win) return;
+    this.isOnline = win.navigator?.onLine ?? true;
+    win.addEventListener?.("online", () => {
+      this.isOnline = true;
+      this.flushOfflineQueue().catch(() => {
+      });
+    });
+    win.addEventListener?.("offline", () => {
+      this.isOnline = false;
+    });
+  }
+  async flushOfflineQueue() {
+    if (this.offlineQueue.length === 0) {
+      return;
+    }
+    const logsToSend = [...this.offlineQueue];
+    this.offlineQueue = [];
+    this.saveOfflineQueue();
+    try {
+      await this.sendLogs(logsToSend);
+    } catch (error) {
+      this.offlineQueue = [...logsToSend, ...this.offlineQueue];
+      this.saveOfflineQueue();
+      throw error;
+    }
+  }
+  saveOfflineQueue() {
+    if (!this.isBrowser) return;
+    const storage = getBrowserStorage();
+    if (!storage) return;
+    try {
+      const dataToStore = this.offlineQueue.map((log) => ({
+        ...log,
+        timestamp: log.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+        savedAt: (/* @__PURE__ */ new Date()).getTime()
+      }));
+      storage.setItem(OFFLINE_STORAGE_KEY, JSON.stringify(dataToStore));
+    } catch (error) {
+      if (this.config.onError && error instanceof Error) {
+        this.config.onError(error, []);
+      }
+    }
+  }
+  restoreOfflineQueue() {
+    if (!this.isBrowser) return;
+    const storage = getBrowserStorage();
+    if (!storage) return;
+    try {
+      const stored = storage.getItem(OFFLINE_STORAGE_KEY);
+      if (stored) {
+        const logs = JSON.parse(stored);
+        const now = (/* @__PURE__ */ new Date()).getTime();
+        this.offlineQueue = logs.filter((log) => now - log.savedAt < OFFLINE_STORAGE_TTL).map(({ savedAt, ...log }) => log);
+        this.saveOfflineQueue();
+      }
+    } catch (error) {
+      storage.removeItem(OFFLINE_STORAGE_KEY);
+    }
+  }
+  isProductionMode() {
+    return this.config.environment === "production" || this.config.environment === "staging";
+  }
+  /**
+   * Whether this log should be written to the console. Always on in
+   * development/test; in production/staging only when consoleInProduction is set.
+   * `silent` disables console output entirely.
+   */
+  shouldLogToConsole() {
+    if (this.config.silent) {
+      return false;
+    }
+    if (this.isProductionMode()) {
+      return this.config.consoleInProduction;
+    }
+    return true;
+  }
+  /**
+   * Append logs to the offline queue, dropping the oldest entries past the
+   * configured cap to avoid exceeding localStorage quota.
+   */
+  enqueueOffline(logs) {
+    this.offlineQueue.push(...logs);
+    const max = this.config.maxOfflineQueueSize;
+    if (this.offlineQueue.length > max) {
+      this.offlineQueue = this.offlineQueue.slice(-max);
+    }
+    this.saveOfflineQueue();
+  }
+  captureDefaultContext() {
+    this.globalContext = getBrowserContext();
+  }
+  formatTimestamp(timestamp) {
+    const date = new Date(timestamp);
+    return date.toISOString().replace("T", " ").slice(0, 23);
+  }
+  logToConsole(entry) {
+    const timestamp = this.formatTimestamp(
+      entry.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+    );
+    const level = entry.level.toUpperCase().padEnd(8);
+    if (this.isBrowser) {
+      const style = BROWSER_STYLES[entry.level];
+      const contextStr = entry.context?.url ? ` [${entry.context.url}]` : "";
+      console.log(
+        `%c${level}%c ${timestamp}${contextStr} - ${entry.message}`,
+        style,
+        "color: inherit",
+        entry.metadata || ""
+      );
+    } else {
+      const color = LEVEL_COLORS[entry.level];
+      const contextStr = entry.context?.url ? ` [${entry.context.url}]` : entry.context?.route ? ` [${entry.context.route}]` : "";
+      const metaStr = entry.metadata ? ` ${JSON.stringify(entry.metadata)}` : "";
+      console.log(
+        `${color}${level}${RESET_COLOR} ${timestamp}${contextStr} - ${entry.message}${metaStr}`
+      );
+    }
+  }
+  startFlushTimer() {
+    this.flushTimer = setInterval(() => {
+      if (this.buffer.length > 0 && !this.isFlushing) {
+        this.flush().catch(() => {
+        });
+      }
+    }, this.config.flushInterval);
+  }
+  stopFlushTimer() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+  setContext(context) {
+    this.globalContext = { ...this.globalContext, ...context };
+  }
+  clearContext() {
+    this.globalContext = {};
+    if (this.config.captureContext && this.isBrowser) {
+      this.captureDefaultContext();
+    }
+  }
+  debug(message, metadata) {
+    this.log({ level: "debug", message, metadata });
+  }
+  info(message, metadata) {
+    this.log({ level: "info", message, metadata });
+  }
+  warn(message, metadata) {
+    this.log({ level: "warn", message, metadata });
+  }
+  error(message, metadata) {
+    this.log({ level: "error", message, metadata });
+  }
+  critical(message, metadata) {
+    this.log({ level: "critical", message, metadata });
+  }
+  fatal(message, metadata) {
+    this.log({ level: "fatal", message, metadata });
+  }
+  log(entry) {
+    if (this.isClosing) {
+      console.warn("Logstack: Cannot log after close() has been called");
+      return;
+    }
+    const timestamp = entry.timestamp || (/* @__PURE__ */ new Date()).toISOString();
+    const context = {
+      ...this.globalContext,
+      ...entry.context
+    };
+    const logEntry = {
+      ...entry,
+      timestamp,
+      context: Object.keys(context).length > 0 ? context : void 0
+    };
+    if (this.shouldLogToConsole()) {
+      this.logToConsole(logEntry);
+    }
+    if (this.config.disabled) {
+      return;
+    }
+    if (!this.isOnline) {
+      this.enqueueOffline([logEntry]);
+      return;
+    }
+    this.buffer.push(logEntry);
+    if (this.buffer.length >= this.config.batchSize && !this.isFlushing) {
+      this.flush().catch(() => {
+      });
+    }
+  }
+  async flush() {
+    if (this.config.disabled) {
+      return;
+    }
+    if (this.buffer.length === 0 || this.isFlushing) {
+      return;
+    }
+    this.isFlushing = true;
+    const logsToSend = [...this.buffer];
+    this.buffer = [];
+    try {
+      await this.sendLogs(logsToSend);
+    } catch (error) {
+      this.buffer = [...logsToSend, ...this.buffer];
+      if (this.config.onError && error instanceof Error) {
+        this.config.onError(error, logsToSend);
+      }
+      throw error;
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+  async sendLogs(logs, attempt = 1) {
+    try {
+      const response = await fetch(`${this.config.endpoint}/v1/logs`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify({ logs })
+      });
+      if (!response.ok) {
+        if (response.status >= 500 && attempt < this.config.maxRetries) {
+          const delay = RETRY_BASE_DELAY * Math.pow(2, attempt - 1) + Math.random() * 100;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          return this.sendLogs(logs, attempt + 1);
+        }
+        let errorData = {
+          code: "SEND_ERROR",
+          message: `Failed to send logs: ${response.status}`
+        };
+        try {
+          const data = await response.json();
+          if (data && data.code && data.message) {
+            errorData = data;
+          }
+        } catch {
+        }
+        throw new LogStackError(
+          errorData.code,
+          errorData.message,
+          response.status
+        );
+      }
+    } catch (error) {
+      if (this.isOnline && error instanceof Error) {
+        this.enqueueOffline(logs);
+        this.isOnline = false;
+        throw error;
+      }
+      throw error;
+    }
+  }
+  async getLogs(options = {}) {
+    if (!this.config.projectId) {
+      throw new LogStackError(
+        "MISSING_PROJECT_ID",
+        "projectId is required in config for query operations",
+        400
+      );
+    }
+    const params = new URLSearchParams();
+    params.set("projectId", this.config.projectId);
+    if (options.level) params.set("level", options.level);
+    if (options.search) params.set("search", options.search);
+    if (options.startTime) params.set("startTime", options.startTime);
+    if (options.endTime) params.set("endTime", options.endTime);
+    if (options.offset !== void 0)
+      params.set("offset", String(options.offset));
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const response = await this.fetchWithRetry(
+      `${this.config.endpoint}/v1/logs?${params.toString()}`,
+      { method: "GET" }
+    );
+    return await response.json();
+  }
+  async getLogById(logId) {
+    if (!this.config.projectId) {
+      throw new LogStackError(
+        "MISSING_PROJECT_ID",
+        "projectId is required in config for query operations",
+        400
+      );
+    }
+    const params = new URLSearchParams();
+    params.set("projectId", this.config.projectId);
+    const response = await this.fetchWithRetry(
+      `${this.config.endpoint}/v1/logs/${logId}?${params.toString()}`,
+      { method: "GET" }
+    );
+    return await response.json();
+  }
+  async fetchWithRetry(url, options, attempt = 1) {
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.apiKey}`,
+        ...options.headers
+      }
+    });
+    if (!response.ok) {
+      if (response.status >= 500 && attempt < this.config.maxRetries) {
+        const delay = RETRY_BASE_DELAY * Math.pow(2, attempt - 1) + Math.random() * 100;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        return this.fetchWithRetry(url, options, attempt + 1);
+      }
+      let errorData = {
+        code: "REQUEST_ERROR",
+        message: `Request failed: ${response.status}`
+      };
+      try {
+        const data = await response.json();
+        if (data && data.code && data.message) {
+          errorData = data;
+        }
+      } catch {
+      }
+      throw new LogStackError(
+        errorData.code,
+        errorData.message,
+        response.status
+      );
+    }
+    return response;
+  }
+  async close() {
+    this.isClosing = true;
+    this.stopFlushTimer();
+    if (this.offlineRetryTimer) {
+      clearInterval(this.offlineRetryTimer);
+      this.offlineRetryTimer = null;
+    }
+    if (!this.config.disabled && this.buffer.length > 0) {
+      await this.flush();
+    }
+    if (this.isOnline && this.offlineQueue.length > 0) {
+      try {
+        await this.flushOfflineQueue();
+      } catch {
+      }
+    }
+  }
+};
+function createLogStack(config) {
+  return new LogStack(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LogStackError,
+  createLogStack
+});

package/dist/index.mjs

@@ -0,0 +1,477 @@
+// src/types.ts
+var LogStackError = class extends Error {
+  constructor(code, message, status) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.name = "LogStackError";
+  }
+};
+
+// src/index.ts
+var DEFAULT_ENDPOINT = "https://api.logstack.tech";
+var DEFAULT_BATCH_SIZE = 100;
+var DEFAULT_FLUSH_INTERVAL = 5e3;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_MAX_OFFLINE_QUEUE = 1e3;
+var RETRY_BASE_DELAY = 1e3;
+var OFFLINE_STORAGE_KEY = "logstack_offline_queue";
+var OFFLINE_STORAGE_TTL = 24 * 60 * 60 * 1e3;
+var LEVEL_COLORS = {
+  debug: "\x1B[35m",
+  // Magenta
+  info: "\x1B[36m",
+  // Cyan
+  warn: "\x1B[33m",
+  // Yellow
+  error: "\x1B[31m",
+  // Red
+  critical: "\x1B[41m\x1B[37m",
+  // White on Red background
+  fatal: "\x1B[45m\x1B[37m"
+  // White on Magenta background
+};
+var RESET_COLOR = "\x1B[0m";
+var BROWSER_STYLES = {
+  debug: "color: #a371f7; font-weight: bold",
+  info: "color: #58a6ff; font-weight: bold",
+  warn: "color: #d29922; font-weight: bold",
+  error: "color: #f85149; font-weight: bold",
+  critical: "background: #da3633; color: white; font-weight: bold; padding: 2px 6px; border-radius: 2px",
+  fatal: "background: #8957e5; color: white; font-weight: bold; padding: 2px 6px; border-radius: 2px"
+};
+function isBrowserEnvironment() {
+  return typeof globalThis !== "undefined" && typeof globalThis.window !== "undefined";
+}
+function getBrowserWindow() {
+  if (!isBrowserEnvironment()) {
+    return void 0;
+  }
+  const win = globalThis.window;
+  if (typeof win !== "object" || win === null) {
+    return void 0;
+  }
+  return win;
+}
+function getBrowserStorage() {
+  if (!isBrowserEnvironment()) {
+    return void 0;
+  }
+  const storage = globalThis.localStorage;
+  if (typeof storage !== "object" || storage === null) {
+    return void 0;
+  }
+  return storage;
+}
+function getBrowserContext() {
+  const win = getBrowserWindow();
+  if (!win) {
+    return {};
+  }
+  return {
+    url: win.location?.href,
+    route: win.location?.pathname,
+    userAgent: win.navigator?.userAgent
+  };
+}
+var LogStack = class {
+  constructor(config) {
+    this.buffer = [];
+    this.flushTimer = null;
+    this.isFlushing = false;
+    this.isClosing = false;
+    this.globalContext = {};
+    this.isOnline = true;
+    this.offlineQueue = [];
+    this.offlineRetryTimer = null;
+    this.isBrowser = isBrowserEnvironment();
+    const detectedEnvironment = this.detectEnvironment();
+    this.config = {
+      apiKey: config.apiKey,
+      endpoint: config.endpoint || DEFAULT_ENDPOINT,
+      batchSize: config.batchSize || DEFAULT_BATCH_SIZE,
+      flushInterval: config.flushInterval || DEFAULT_FLUSH_INTERVAL,
+      maxRetries: config.maxRetries || DEFAULT_MAX_RETRIES,
+      environment: config.environment || detectedEnvironment,
+      consoleInProduction: config.consoleInProduction || false,
+      silent: config.silent || false,
+      disabled: config.disabled || false,
+      maxOfflineQueueSize: config.maxOfflineQueueSize ?? DEFAULT_MAX_OFFLINE_QUEUE,
+      captureContext: config.captureContext !== false,
+      onError: config.onError,
+      projectId: config.projectId
+    };
+    if (!this.config.disabled) {
+      this.startFlushTimer();
+    }
+    if (this.config.captureContext && this.isBrowser) {
+      this.captureDefaultContext();
+    }
+    if (this.isBrowser && !this.config.disabled) {
+      this.setupOfflineDetection();
+      this.restoreOfflineQueue();
+    }
+  }
+  detectEnvironment() {
+    if (typeof process !== "undefined" && process.env) {
+      const nodeEnv = process.env.NODE_ENV;
+      if (nodeEnv === "development" || nodeEnv === "dev") return "development";
+      if (nodeEnv === "test") return "test";
+      if (nodeEnv === "staging") return "staging";
+    }
+    return "production";
+  }
+  setupOfflineDetection() {
+    const win = getBrowserWindow();
+    if (!win) return;
+    this.isOnline = win.navigator?.onLine ?? true;
+    win.addEventListener?.("online", () => {
+      this.isOnline = true;
+      this.flushOfflineQueue().catch(() => {
+      });
+    });
+    win.addEventListener?.("offline", () => {
+      this.isOnline = false;
+    });
+  }
+  async flushOfflineQueue() {
+    if (this.offlineQueue.length === 0) {
+      return;
+    }
+    const logsToSend = [...this.offlineQueue];
+    this.offlineQueue = [];
+    this.saveOfflineQueue();
+    try {
+      await this.sendLogs(logsToSend);
+    } catch (error) {
+      this.offlineQueue = [...logsToSend, ...this.offlineQueue];
+      this.saveOfflineQueue();
+      throw error;
+    }
+  }
+  saveOfflineQueue() {
+    if (!this.isBrowser) return;
+    const storage = getBrowserStorage();
+    if (!storage) return;
+    try {
+      const dataToStore = this.offlineQueue.map((log) => ({
+        ...log,
+        timestamp: log.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+        savedAt: (/* @__PURE__ */ new Date()).getTime()
+      }));
+      storage.setItem(OFFLINE_STORAGE_KEY, JSON.stringify(dataToStore));
+    } catch (error) {
+      if (this.config.onError && error instanceof Error) {
+        this.config.onError(error, []);
+      }
+    }
+  }
+  restoreOfflineQueue() {
+    if (!this.isBrowser) return;
+    const storage = getBrowserStorage();
+    if (!storage) return;
+    try {
+      const stored = storage.getItem(OFFLINE_STORAGE_KEY);
+      if (stored) {
+        const logs = JSON.parse(stored);
+        const now = (/* @__PURE__ */ new Date()).getTime();
+        this.offlineQueue = logs.filter((log) => now - log.savedAt < OFFLINE_STORAGE_TTL).map(({ savedAt, ...log }) => log);
+        this.saveOfflineQueue();
+      }
+    } catch (error) {
+      storage.removeItem(OFFLINE_STORAGE_KEY);
+    }
+  }
+  isProductionMode() {
+    return this.config.environment === "production" || this.config.environment === "staging";
+  }
+  /**
+   * Whether this log should be written to the console. Always on in
+   * development/test; in production/staging only when consoleInProduction is set.
+   * `silent` disables console output entirely.
+   */
+  shouldLogToConsole() {
+    if (this.config.silent) {
+      return false;
+    }
+    if (this.isProductionMode()) {
+      return this.config.consoleInProduction;
+    }
+    return true;
+  }
+  /**
+   * Append logs to the offline queue, dropping the oldest entries past the
+   * configured cap to avoid exceeding localStorage quota.
+   */
+  enqueueOffline(logs) {
+    this.offlineQueue.push(...logs);
+    const max = this.config.maxOfflineQueueSize;
+    if (this.offlineQueue.length > max) {
+      this.offlineQueue = this.offlineQueue.slice(-max);
+    }
+    this.saveOfflineQueue();
+  }
+  captureDefaultContext() {
+    this.globalContext = getBrowserContext();
+  }
+  formatTimestamp(timestamp) {
+    const date = new Date(timestamp);
+    return date.toISOString().replace("T", " ").slice(0, 23);
+  }
+  logToConsole(entry) {
+    const timestamp = this.formatTimestamp(
+      entry.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+    );
+    const level = entry.level.toUpperCase().padEnd(8);
+    if (this.isBrowser) {
+      const style = BROWSER_STYLES[entry.level];
+      const contextStr = entry.context?.url ? ` [${entry.context.url}]` : "";
+      console.log(
+        `%c${level}%c ${timestamp}${contextStr} - ${entry.message}`,
+        style,
+        "color: inherit",
+        entry.metadata || ""
+      );
+    } else {
+      const color = LEVEL_COLORS[entry.level];
+      const contextStr = entry.context?.url ? ` [${entry.context.url}]` : entry.context?.route ? ` [${entry.context.route}]` : "";
+      const metaStr = entry.metadata ? ` ${JSON.stringify(entry.metadata)}` : "";
+      console.log(
+        `${color}${level}${RESET_COLOR} ${timestamp}${contextStr} - ${entry.message}${metaStr}`
+      );
+    }
+  }
+  startFlushTimer() {
+    this.flushTimer = setInterval(() => {
+      if (this.buffer.length > 0 && !this.isFlushing) {
+        this.flush().catch(() => {
+        });
+      }
+    }, this.config.flushInterval);
+  }
+  stopFlushTimer() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+  setContext(context) {
+    this.globalContext = { ...this.globalContext, ...context };
+  }
+  clearContext() {
+    this.globalContext = {};
+    if (this.config.captureContext && this.isBrowser) {
+      this.captureDefaultContext();
+    }
+  }
+  debug(message, metadata) {
+    this.log({ level: "debug", message, metadata });
+  }
+  info(message, metadata) {
+    this.log({ level: "info", message, metadata });
+  }
+  warn(message, metadata) {
+    this.log({ level: "warn", message, metadata });
+  }
+  error(message, metadata) {
+    this.log({ level: "error", message, metadata });
+  }
+  critical(message, metadata) {
+    this.log({ level: "critical", message, metadata });
+  }
+  fatal(message, metadata) {
+    this.log({ level: "fatal", message, metadata });
+  }
+  log(entry) {
+    if (this.isClosing) {
+      console.warn("Logstack: Cannot log after close() has been called");
+      return;
+    }
+    const timestamp = entry.timestamp || (/* @__PURE__ */ new Date()).toISOString();
+    const context = {
+      ...this.globalContext,
+      ...entry.context
+    };
+    const logEntry = {
+      ...entry,
+      timestamp,
+      context: Object.keys(context).length > 0 ? context : void 0
+    };
+    if (this.shouldLogToConsole()) {
+      this.logToConsole(logEntry);
+    }
+    if (this.config.disabled) {
+      return;
+    }
+    if (!this.isOnline) {
+      this.enqueueOffline([logEntry]);
+      return;
+    }
+    this.buffer.push(logEntry);
+    if (this.buffer.length >= this.config.batchSize && !this.isFlushing) {
+      this.flush().catch(() => {
+      });
+    }
+  }
+  async flush() {
+    if (this.config.disabled) {
+      return;
+    }
+    if (this.buffer.length === 0 || this.isFlushing) {
+      return;
+    }
+    this.isFlushing = true;
+    const logsToSend = [...this.buffer];
+    this.buffer = [];
+    try {
+      await this.sendLogs(logsToSend);
+    } catch (error) {
+      this.buffer = [...logsToSend, ...this.buffer];
+      if (this.config.onError && error instanceof Error) {
+        this.config.onError(error, logsToSend);
+      }
+      throw error;
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+  async sendLogs(logs, attempt = 1) {
+    try {
+      const response = await fetch(`${this.config.endpoint}/v1/logs`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`
+        },
+        body: JSON.stringify({ logs })
+      });
+      if (!response.ok) {
+        if (response.status >= 500 && attempt < this.config.maxRetries) {
+          const delay = RETRY_BASE_DELAY * Math.pow(2, attempt - 1) + Math.random() * 100;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          return this.sendLogs(logs, attempt + 1);
+        }
+        let errorData = {
+          code: "SEND_ERROR",
+          message: `Failed to send logs: ${response.status}`
+        };
+        try {
+          const data = await response.json();
+          if (data && data.code && data.message) {
+            errorData = data;
+          }
+        } catch {
+        }
+        throw new LogStackError(
+          errorData.code,
+          errorData.message,
+          response.status
+        );
+      }
+    } catch (error) {
+      if (this.isOnline && error instanceof Error) {
+        this.enqueueOffline(logs);
+        this.isOnline = false;
+        throw error;
+      }
+      throw error;
+    }
+  }
+  async getLogs(options = {}) {
+    if (!this.config.projectId) {
+      throw new LogStackError(
+        "MISSING_PROJECT_ID",
+        "projectId is required in config for query operations",
+        400
+      );
+    }
+    const params = new URLSearchParams();
+    params.set("projectId", this.config.projectId);
+    if (options.level) params.set("level", options.level);
+    if (options.search) params.set("search", options.search);
+    if (options.startTime) params.set("startTime", options.startTime);
+    if (options.endTime) params.set("endTime", options.endTime);
+    if (options.offset !== void 0)
+      params.set("offset", String(options.offset));
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const response = await this.fetchWithRetry(
+      `${this.config.endpoint}/v1/logs?${params.toString()}`,
+      { method: "GET" }
+    );
+    return await response.json();
+  }
+  async getLogById(logId) {
+    if (!this.config.projectId) {
+      throw new LogStackError(
+        "MISSING_PROJECT_ID",
+        "projectId is required in config for query operations",
+        400
+      );
+    }
+    const params = new URLSearchParams();
+    params.set("projectId", this.config.projectId);
+    const response = await this.fetchWithRetry(
+      `${this.config.endpoint}/v1/logs/${logId}?${params.toString()}`,
+      { method: "GET" }
+    );
+    return await response.json();
+  }
+  async fetchWithRetry(url, options, attempt = 1) {
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.apiKey}`,
+        ...options.headers
+      }
+    });
+    if (!response.ok) {
+      if (response.status >= 500 && attempt < this.config.maxRetries) {
+        const delay = RETRY_BASE_DELAY * Math.pow(2, attempt - 1) + Math.random() * 100;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        return this.fetchWithRetry(url, options, attempt + 1);
+      }
+      let errorData = {
+        code: "REQUEST_ERROR",
+        message: `Request failed: ${response.status}`
+      };
+      try {
+        const data = await response.json();
+        if (data && data.code && data.message) {
+          errorData = data;
+        }
+      } catch {
+      }
+      throw new LogStackError(
+        errorData.code,
+        errorData.message,
+        response.status
+      );
+    }
+    return response;
+  }
+  async close() {
+    this.isClosing = true;
+    this.stopFlushTimer();
+    if (this.offlineRetryTimer) {
+      clearInterval(this.offlineRetryTimer);
+      this.offlineRetryTimer = null;
+    }
+    if (!this.config.disabled && this.buffer.length > 0) {
+      await this.flush();
+    }
+    if (this.isOnline && this.offlineQueue.length > 0) {
+      try {
+        await this.flushOfflineQueue();
+      } catch {
+      }
+    }
+  }
+};
+function createLogStack(config) {
+  return new LogStack(config);
+}
+export {
+  LogStackError,
+  createLogStack
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "logstack-js",
+  "version": "1.0.0",
+  "description": "Logstack JavaScript/TypeScript SDK for log ingestion and querying",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "logstack",
+    "logging",
+    "logs",
+    "monitoring",
+    "observability"
+  ],
+  "author": "Mosesedem",
+  "license": "MIT",
+  "homepage": "https://github.com/Mosesedem/logstack/tree/main/packages/logstack-js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mosesedem/logstack.git",
+    "directory": "packages/logstack-js"
+  },
+  "bugs": {
+    "url": "https://github.com/Mosesedem/logstack/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "eslint": "^8.55.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}