@gunsole/core

Gunsole JavaScript/TypeScript SDK for browser and Node.js environments.

Installation

pnpm add @gunsole/core
# or
npm install @gunsole/core
# or
yarn add @gunsole/core

Usage

Basic Setup

import { createGunsoleClient } from "@gunsole/core";

const gunsole = createGunsoleClient({
  projectId: "your-project-id",
  mode: "desktop", // or "cloud" | "local"
  env: "production",
  appName: "my-app",
  appVersion: "1.0.0",
});

Logging

// Simple log (defaults to info level)
gunsole.log({
  bucket: "user_action",
  message: "User clicked button",
});

// Log with explicit level
gunsole.log("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

gunsole.setUser({
  id: "user-123",
  email: "[email protected]",
  name: "John Doe",
  traits: {
    plan: "premium",
    signupDate: "2024-01-01",
  },
});

Session Tracking

gunsole.setSessionId("session-abc-123");

Global Error Handlers

// Attach automatic error tracking
gunsole.attachGlobalErrorHandlers();

// Detach when done
gunsole.detachGlobalErrorHandlers();

The global error handlers log to the following built-in buckets:

• unhandled_rejection — unhandled promise rejections (browser and Node.js)
• global_error — uncaught errors via window.onerror (browser only)
• uncaught_exception — uncaught exceptions via process.on('uncaughtException') (Node.js only)

Manual Flush

// 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:17655 (Gunsole Desktop app)
• local: Sends logs to https://local.gunsole.com (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, min: 1)
• flushInterval (optional): Auto-flush interval in ms (default: 5000, min: 100)
• buckets (optional): Array of bucket names to generate typed accessor methods (e.g., ["payment", "auth"])
• fetch (optional): Custom fetch implementation (default: global fetch; requires Node.js 18+)

Cleanup

// 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 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

# Install dependencies
pnpm install

# Build
pnpm build

# Test
pnpm test

# Lint
pnpm lint

# Type check
pnpm typecheck

License

MIT