@gunsole/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 push1kb
+
+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,162 @@
+# @gunsole/core
+
+Gunsole JavaScript/TypeScript SDK for browser and Node.js environments.
+
+## Installation
+
+```bash
+pnpm add @gunsole/core
+# or
+npm install @gunsole/core
+# or
+yarn add @gunsole/core
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { createGunsoleClient } from "@gunsole/core";
+
+const gunsole = createGunsoleClient({
+  projectId: "your-project-id",
+  apiKey: "your-api-key",
+  mode: "cloud", // or "desktop" | "local"
+  env: "production",
+  appName: "my-app",
+  appVersion: "1.0.0",
+});
+```
+
+### Logging
+
+```typescript
+// Simple log
+gunsole.log({
+  level: "info",
+  bucket: "user_action",
+  message: "User clicked button",
+});
+
+// Log with context and tags
+gunsole.log({
+  level: "error",
+  bucket: "api_error",
+  message: "Failed to fetch user data",
+  context: {
+    userId: "123",
+    endpoint: "/api/users",
+    statusCode: 500,
+  },
+  tags: {
+    feature: "user-management",
+    severity: "high",
+  },
+});
+```
+
+### User Tracking
+
+```typescript
+gunsole.setUser({
+  id: "user-123",
+  email: "user@example.com",
+  name: "John Doe",
+  traits: {
+    plan: "premium",
+    signupDate: "2024-01-01",
+  },
+});
+```
+
+### Session Tracking
+
+```typescript
+gunsole.setSessionId("session-abc-123");
+```
+
+### Global Error Handlers
+
+```typescript
+// Attach automatic error tracking
+gunsole.attachGlobalErrorHandlers();
+
+// Detach when done
+gunsole.detachGlobalErrorHandlers();
+```
+
+### Manual Flush
+
+```typescript
+// Flush pending logs immediately
+await gunsole.flush();
+```
+
+## Configuration
+
+### Modes
+
+- `cloud`: Sends logs to `https://api.gunsole.com` (default for SaaS)
+- `desktop`: Sends logs to `http://localhost:8787` (Gunsole Desktop app)
+- `local`: Sends logs to `http://localhost:17655` (local development)
+
+### Options
+
+- `projectId` (required): Your Gunsole project identifier
+- `apiKey` (optional): Your API key (required for cloud mode)
+- `mode` (required): Client mode (`"desktop" | "local" | "cloud"`)
+- `endpoint` (optional): Custom endpoint URL (overrides mode default)
+- `env` (optional): Environment name (e.g., "production", "staging")
+- `appName` (optional): Application name
+- `appVersion` (optional): Application version
+- `defaultTags` (optional): Default tags applied to all logs
+- `batchSize` (optional): Number of logs to batch before sending (default: 10)
+- `flushInterval` (optional): Auto-flush interval in ms (default: 5000)
+
+### Cleanup
+
+```typescript
+// Flush remaining logs and release resources
+await gunsole.destroy();
+```
+
+> **Node.js note:** The `attachGlobalErrorHandlers()` method registers an `uncaughtException` listener. Be aware that in Node.js, uncaught exceptions leave the process in an undefined state. The SDK captures the error for logging but does not re-throw or exit — you may want to add your own handler that calls `process.exit(1)` after flushing.
+
+## API Reference
+
+See [SDK Reference](../../docs/sdk-reference.md) for full API documentation including typed buckets, tag schemas, and all configuration options.
+
+## Features
+
+- ✅ Browser and Node.js support
+- ✅ Automatic batching and flushing
+- ✅ Retry logic with exponential backoff
+- ✅ Never crashes the host application
+- ✅ TypeScript support with full type definitions
+- ✅ Tree-shakeable ESM and CJS builds
+- ✅ Global error handler integration
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Test
+pnpm test
+
+# Lint
+pnpm lint
+
+# Type check
+pnpm typecheck
+```
+
+## License
+
+MIT
+

package/dist/index.cjs

@@ -0,0 +1,477 @@
+'use strict';
+
+// src/buckets.ts
+var RESERVED_NAMES = /* @__PURE__ */ new Set([
+  "log",
+  "info",
+  "debug",
+  "warn",
+  "error",
+  "setUser",
+  "setSessionId",
+  "flush",
+  "destroy",
+  "attachGlobalErrorHandlers",
+  "detachGlobalErrorHandlers"
+]);
+function createBucketLogger(client, bucketName) {
+  const logAtLevel = (level, message, options) => {
+    client.log(level, {
+      ...options,
+      message,
+      bucket: bucketName
+    });
+  };
+  const logger = ((message, options) => {
+    logAtLevel("info", message, options);
+  });
+  logger.info = (message, options) => logAtLevel("info", message, options);
+  logger.debug = (message, options) => logAtLevel("debug", message, options);
+  logger.warn = (message, options) => logAtLevel("warn", message, options);
+  logger.error = (message, options) => logAtLevel("error", message, options);
+  return logger;
+}
+function attachBuckets(client, buckets) {
+  for (const name of buckets) {
+    if (RESERVED_NAMES.has(name)) {
+      throw new Error(
+        `Bucket name "${name}" conflicts with a reserved GunsoleClient method`
+      );
+    }
+    client[name] = createBucketLogger(client, name);
+  }
+  return client;
+}
+
+// src/config.ts
+var DEFAULT_ENDPOINTS = {
+  desktop: "http://localhost:8787",
+  local: "http://localhost:17655",
+  cloud: "https://api.gunsole.com"
+};
+var DEFAULT_CONFIG = {
+  batchSize: 10,
+  flushInterval: 5e3
+};
+function resolveEndpoint(mode, customEndpoint) {
+  if (customEndpoint) {
+    return customEndpoint;
+  }
+  return DEFAULT_ENDPOINTS[mode];
+}
+function normalizeConfig(config) {
+  if (!config.projectId) {
+    throw new Error("projectId is required");
+  }
+  return {
+    projectId: config.projectId,
+    apiKey: config.apiKey ?? "",
+    mode: config.mode,
+    endpoint: resolveEndpoint(config.mode, config.endpoint),
+    env: config.env ?? "",
+    appName: config.appName ?? "",
+    appVersion: config.appVersion ?? "",
+    defaultTags: config.defaultTags ?? {},
+    batchSize: config.batchSize ?? DEFAULT_CONFIG.batchSize,
+    flushInterval: config.flushInterval ?? DEFAULT_CONFIG.flushInterval,
+    fetch: config.fetch,
+    isDebug: config.isDebug ?? false,
+    isDisabled: config.isDisabled ?? false,
+    buckets: config.buckets ?? []
+  };
+}
+
+// src/utils/env.ts
+function isBrowser() {
+  return typeof window !== "undefined" && typeof window.document !== "undefined";
+}
+function isNode() {
+  return typeof process !== "undefined" && typeof process.versions !== "undefined" && typeof process.versions.node !== "undefined";
+}
+function getFetch(customFetch) {
+  if (isBrowser()) {
+    return window.fetch.bind(window);
+  }
+  if (isNode()) {
+    if (typeof globalThis.fetch !== "undefined") {
+      return globalThis.fetch;
+    }
+    throw new Error(
+      "fetch is not available. Please use Node.js 18+ or provide a custom fetch implementation in the config"
+    );
+  }
+  throw new Error("Unsupported environment: neither browser nor Node.js");
+}
+
+// src/transport.ts
+var MAX_RETRIES = 3;
+var BASE_DELAY_MS = 1e3;
+function calculateBackoffDelay(attempt) {
+  return BASE_DELAY_MS * 2 ** attempt;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function gzipCompress(input) {
+  const encoder = new TextEncoder();
+  const stream = new Blob([encoder.encode(input)]).stream().pipeThrough(new CompressionStream("gzip"));
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+async function compressPayload(payload, isDebug) {
+  const minified = JSON.stringify(payload);
+  if (isDebug) {
+    return minified;
+  }
+  return gzipCompress(minified);
+}
+var Transport = class {
+  constructor(endpoint, apiKey, projectId, fetch, isDebug = false) {
+    this.endpoint = endpoint;
+    this.apiKey = apiKey;
+    this.projectId = projectId;
+    this.fetch = fetch ?? getFetch();
+    this.isDebug = isDebug;
+  }
+  /**
+   * Send a batch of logs to the API
+   * Implements retry logic with exponential backoff
+   */
+  async sendBatch(logs) {
+    if (logs.length === 0) {
+      return;
+    }
+    const payload = {
+      projectId: this.projectId,
+      logs
+    };
+    let lastError = null;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      try {
+        const body = await compressPayload(payload, this.isDebug);
+        const headers = {
+          "Content-Type": "application/json"
+        };
+        if (this.apiKey) {
+          headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        if (!this.isDebug) {
+          headers["Content-Encoding"] = "gzip";
+        }
+        const response = await this.fetch(`${this.endpoint}/logs`, {
+          method: "POST",
+          headers,
+          body
+        });
+        if (response.ok) {
+          return;
+        }
+        const errorText = await response.text().catch(() => "Unknown error");
+        lastError = new Error(`HTTP ${response.status}: ${errorText}`);
+        if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+          break;
+        }
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+      }
+      if (attempt < MAX_RETRIES - 1) {
+        const delay = calculateBackoffDelay(attempt);
+        await sleep(delay);
+      }
+    }
+    if (process.env.NODE_ENV === "development") {
+      console.warn("[Gunsole] Failed to send logs after retries:", lastError);
+    }
+  }
+};
+
+// src/client.ts
+var GunsoleClient = class {
+  constructor(config) {
+    this.batch = [];
+    this.flushTimer = null;
+    this.user = null;
+    this.sessionId = null;
+    this.globalHandlers = { attached: false };
+    this.config = normalizeConfig(config);
+    this.disabled = config.isDisabled ?? false;
+    this.transport = new Transport(
+      this.config.endpoint,
+      this.config.apiKey,
+      this.config.projectId,
+      this.config.fetch,
+      config.isDebug ?? false
+    );
+    if (this.disabled) {
+      return;
+    }
+    this.startFlushTimer();
+  }
+  log(levelOrOptions, maybeOptions) {
+    if (this.disabled) {
+      return;
+    }
+    const level = typeof levelOrOptions === "string" ? levelOrOptions : "info";
+    const options = typeof levelOrOptions === "string" ? maybeOptions : levelOrOptions;
+    try {
+      const internalEntry = {
+        level,
+        bucket: options.bucket,
+        message: options.message,
+        context: options.context,
+        timestamp: Date.now(),
+        traceId: options.traceId,
+        userId: this.user?.id,
+        sessionId: this.sessionId ?? void 0,
+        env: this.config.env || void 0,
+        appName: this.config.appName || void 0,
+        appVersion: this.config.appVersion || void 0,
+        tags: {
+          ...this.config.defaultTags,
+          ...Array.isArray(options.tags) ? Object.assign({}, ...options.tags) : options.tags
+        }
+      };
+      this.batch.push(internalEntry);
+      if (this.batch.length >= this.config.batchSize) {
+        this.flush();
+      }
+    } catch (error) {
+      if (process.env.NODE_ENV === "development") {
+        console.warn("[Gunsole] Error in log():", error);
+      }
+    }
+  }
+  /**
+   * Log an info-level message
+   */
+  info(options) {
+    this.log("info", options);
+  }
+  debug(options) {
+    this.log("debug", options);
+  }
+  warn(options) {
+    this.log("warn", options);
+  }
+  error(options) {
+    this.log("error", options);
+  }
+  /**
+   * Set user information
+   */
+  setUser(user) {
+    if (this.disabled) {
+      return;
+    }
+    try {
+      this.user = user;
+    } catch (error) {
+      if (process.env.NODE_ENV === "development") {
+        console.warn("[Gunsole] Error in setUser():", error);
+      }
+    }
+  }
+  /**
+   * Set session ID
+   */
+  setSessionId(sessionId) {
+    if (this.disabled) {
+      return;
+    }
+    try {
+      this.sessionId = sessionId;
+    } catch (error) {
+      if (process.env.NODE_ENV === "development") {
+        console.warn("[Gunsole] Error in setSessionId():", error);
+      }
+    }
+  }
+  /**
+   * Flush pending logs to the API
+   */
+  async flush() {
+    if (this.disabled) {
+      return;
+    }
+    try {
+      if (this.batch.length === 0) {
+        return;
+      }
+      const logsToSend = [...this.batch];
+      this.batch = [];
+      await this.transport.sendBatch(logsToSend);
+    } catch (error) {
+      if (process.env.NODE_ENV === "development") {
+        console.warn("[Gunsole] Error in flush():", error);
+      }
+    }
+  }
+  /**
+   * Attach global error handlers
+   */
+  attachGlobalErrorHandlers() {
+    if (this.disabled) {
+      return;
+    }
+    try {
+      if (this.globalHandlers.attached) {
+        return;
+      }
+      this.globalHandlers.unhandledRejection = (event) => {
+        this.error({
+          message: "Unhandled promise rejection",
+          bucket: "unhandled_rejection",
+          context: {
+            reason: String(event.reason),
+            error: event.reason instanceof Error ? {
+              name: event.reason.name,
+              message: event.reason.message,
+              stack: event.reason.stack
+            } : event.reason
+          }
+        });
+      };
+      this.globalHandlers.error = (event) => {
+        this.error({
+          message: event.message || "Global error",
+          bucket: "global_error",
+          context: {
+            filename: event.filename,
+            lineno: event.lineno,
+            colno: event.colno,
+            error: event.error ? {
+              name: event.error.name,
+              message: event.error.message,
+              stack: event.error.stack
+            } : void 0
+          }
+        });
+      };
+      if (typeof window !== "undefined") {
+        window.addEventListener(
+          "unhandledrejection",
+          this.globalHandlers.unhandledRejection
+        );
+        window.addEventListener("error", this.globalHandlers.error);
+      }
+      if (typeof process !== "undefined") {
+        this.globalHandlers.unhandledRejectionNode = (reason, _promise) => {
+          this.error({
+            message: "Unhandled promise rejection",
+            bucket: "unhandled_rejection",
+            context: {
+              reason: String(reason),
+              error: reason instanceof Error ? {
+                name: reason.name,
+                message: reason.message,
+                stack: reason.stack
+              } : reason
+            }
+          });
+        };
+        this.globalHandlers.uncaughtException = (error) => {
+          this.error({
+            message: error.message,
+            bucket: "uncaught_exception",
+            context: {
+              name: error.name,
+              stack: error.stack
+            }
+          });
+        };
+        process.on(
+          "unhandledRejection",
+          this.globalHandlers.unhandledRejectionNode
+        );
+        process.on("uncaughtException", this.globalHandlers.uncaughtException);
+      }
+      this.globalHandlers.attached = true;
+    } catch (error) {
+      if (process.env.NODE_ENV === "development") {
+        console.warn("[Gunsole] Error in attachGlobalErrorHandlers():", error);
+      }
+    }
+  }
+  /**
+   * Detach global error handlers
+   */
+  detachGlobalErrorHandlers() {
+    try {
+      if (!this.globalHandlers.attached) {
+        return;
+      }
+      if (typeof window !== "undefined") {
+        if (this.globalHandlers.unhandledRejection) {
+          window.removeEventListener(
+            "unhandledrejection",
+            this.globalHandlers.unhandledRejection
+          );
+        }
+        if (this.globalHandlers.error) {
+          window.removeEventListener("error", this.globalHandlers.error);
+        }
+      }
+      if (typeof process !== "undefined") {
+        if (this.globalHandlers.unhandledRejectionNode) {
+          process.removeListener(
+            "unhandledRejection",
+            this.globalHandlers.unhandledRejectionNode
+          );
+        }
+        if (this.globalHandlers.uncaughtException) {
+          process.removeListener(
+            "uncaughtException",
+            this.globalHandlers.uncaughtException
+          );
+        }
+      }
+      this.globalHandlers = { attached: false };
+    } catch (error) {
+      if (process.env.NODE_ENV === "development") {
+        console.warn("[Gunsole] Error in detachGlobalErrorHandlers():", error);
+      }
+    }
+  }
+  /**
+   * Start the automatic flush timer
+   */
+  startFlushTimer() {
+    if (this.flushTimer) {
+      return;
+    }
+    this.flushTimer = setInterval(() => {
+      this.flush();
+    }, this.config.flushInterval);
+  }
+  /**
+   * Stop the automatic flush timer
+   */
+  stopFlushTimer() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+  /**
+   * Cleanup resources. Awaiting ensures remaining logs are flushed.
+   */
+  async destroy() {
+    this.stopFlushTimer();
+    this.detachGlobalErrorHandlers();
+    await this.flush();
+  }
+};
+
+// src/factory.ts
+function createGunsoleClient(config) {
+  const client = new GunsoleClient(config);
+  const buckets = config.buckets ?? [];
+  if (buckets.length > 0) {
+    return attachBuckets(client, buckets);
+  }
+  return client;
+}
+
+exports.GunsoleClient = GunsoleClient;
+exports.createGunsoleClient = createGunsoleClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map