Smart Grow Logs - Web SDK

Secure logging SDK for web applications.

Features

• 📱 Auto device detection - OS, browser, screen size
• 🎯 TypeScript support - Full type definitions
• 📦 Tree-shakeable - Only import what you need

Prerequisites

Before using this SDK, you need to:

1. Sign up for a free account at logs.smart-grow.app
2. Create a new project in the dashboard
3. Get your API key from the project settings

The SDK requires an active Smart Grow Logs account to function. All logs are securely transmitted to your Smart Grow Logs dashboard.

Installation

npm install @smart-dev-agency/smart-grow-logs
# or
yarn add @smart-dev-agency/smart-grow-logs
# or
pnpm add @smart-dev-agency/smart-grow-logs

Quick Start

import { SmartGrowLogs, LogLevel } from '@smart-dev-agency/smart-grow-logs';

// Initialize the SDK (do this once at app startup)
await SmartGrowLogs.initialize({
  apiKey: 'sgl_your_api_key_here',
  baseUrl: 'https://logs-api.smart-grow.app/',
  debug: true // Optional: enable console logging
});

// Send logs using convenience methods
await SmartGrowLogs.info('User logged in successfully');
await SmartGrowLogs.error('Failed to load data');

// Or use sendLog for full control
await SmartGrowLogs.sendLog({
  level: LogLevel.Error,
  message: 'Payment processing failed',
  stackTrace: new Error().stack,
  metadata: {
    orderId: 'ORD-123',
    amount: 99.99,
    currency: 'USD'
  },
  userIdentifier: '[email protected]',
  sessionId: 'sess_abc123'
});

API Reference

SmartGrowLogs.initialize(options)

Initialize the SDK. Must be called before sending any logs.

interface InitOptions {
  apiKey: string;    // Required: Your API key
  baseUrl: string;   // Required: Server URL
  debug?: boolean;   // Optional: Enable debug logging (default: false)
}

SmartGrowLogs.sendLog(options)

Send a log entry with full control over all fields.

interface LogOptions {
  level: LogLevel;                    // Required: Log level
  message: string;                    // Required: Log message
  stackTrace?: string;                // Optional: Error stack trace
  metadata?: Record<string, unknown>; // Optional: Custom metadata
  userIdentifier?: string;            // Optional: User ID/email
  sessionId?: string;                 // Optional: Session ID
}

Convenience Methods

// All return Promise<LogResponse>
await SmartGrowLogs.debug(message, options?);
await SmartGrowLogs.info(message, options?);
await SmartGrowLogs.warn(message, options?);
await SmartGrowLogs.error(message, options?);
await SmartGrowLogs.fatal(message, options?);

LogLevel Enum

enum LogLevel {
  Debug = 'debug',
  Info = 'info',
  Warn = 'warn',
  Error = 'error',
  Fatal = 'fatal'
}

LogResponse

interface LogResponse {
  success: boolean;
  id?: string;      // Log ID from server
  error?: string;   // Error message if failed
}

Auto-Detected Information

The SDK automatically detects and sends:

| Field | Description | Example | | ------------------- | ------------------------------------- | -------------------------------------------- | | device_type | Device category | desktop, mobile, tablet | | os_name | Operating system | Windows, macOS, iOS, Android | | os_version | OS version | 14.0, 10 | | app_version | App version (from meta tag or window) | 1.0.0 | | browser_name | Browser name | Chrome, Firefox, Safari | | browser_version | Browser version | 120.0 | | screen_width | Screen width in pixels | 1920 | | screen_height | Screen height in pixels | 1080 | | language | Browser language | en-US | | timezone | User timezone | America/New_York | | timestamp | ISO 8601 timestamp | 2024-01-15T10:30:00.000Z |

Setting App Version

The SDK tries to detect app version automatically from:

1. <meta name="version" content="1.0.0"> tag
2. <meta name="app-version" content="1.0.0"> tag
3. window.APP_VERSION global variable
4. window.__APP_VERSION__ global variable

Or set it manually in your HTML:

<meta name="version" content="1.2.3">

Error Handling

try {
  await SmartGrowLogs.initialize({
    apiKey: 'sgl_xxx',
    baseUrl: 'https://logs-api.smart-grow.app/'
  });
} catch (error) {
  console.error('Failed to initialize logs:', error);
}

// sendLog returns a response object instead of throwing
const response = await SmartGrowLogs.error('Something went wrong');
if (!response.success) {
  console.error('Failed to send log:', response.error);
}

Framework Integration

React

// src/lib/logger.ts
import { SmartGrowLogs } from '@smart-dev-agency/smart-grow-logs';

export async function initLogger() {
  await SmartGrowLogs.initialize({
    apiKey: import.meta.env.VITE_SMARTGROW_API_KEY,
    baseUrl: import.meta.env.VITE_SMARTGROW_URL,
    debug: import.meta.env.DEV
  });
}

export { SmartGrowLogs, LogLevel } from '@smart-dev-agency/smart-grow-logs';

// src/main.tsx
import { initLogger } from './lib/logger';

initLogger().then(() => {
  ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
});

Vue

// src/plugins/logger.ts
import { SmartGrowLogs } from '@smart-dev-agency/smart-grow-logs';

export default {
  install: async (app) => {
    await SmartGrowLogs.initialize({
      apiKey: import.meta.env.VITE_SMARTGROW_API_KEY,
      baseUrl: import.meta.env.VITE_SMARTGROW_URL
    });
  
    app.config.globalProperties.$log = SmartGrowLogs;
  }
};

Global Error Handling

// Capture all unhandled errors
window.addEventListener('error', (event) => {
  SmartGrowLogs.error(event.message, {
    stackTrace: event.error?.stack,
    metadata: {
      filename: event.filename,
      lineno: event.lineno,
      colno: event.colno
    }
  });
});

// Capture unhandled promise rejections
window.addEventListener('unhandledrejection', (event) => {
  SmartGrowLogs.error('Unhandled Promise Rejection', {
    stackTrace: event.reason?.stack || String(event.reason),
    metadata: { reason: String(event.reason) }
  });
});

Browser Support

• Chrome 87+
• Firefox 78+
• Safari 14+
• Edge 88+

Requires WebAssembly support.

License

MIT