@johnboxcodes/boxlogger 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-02
+
+### Added
+- Initial release
+- Sentry-compatible API with top 5 functions (captureException, captureMessage, setUser, addBreadcrumb, withScope)
+- SQLite storage provider with persistent logging
+- Memory storage provider for development/testing
+- Session tracking with crash detection
+- Transaction support for performance monitoring
+- Breadcrumb trail for debugging
+- Scoped context with tags and metadata
+- Configurable sampling rates
+- Error filtering with ignoreErrors patterns
+- beforeSend and beforeSendMessage hooks
+- Comprehensive TypeScript types
+- Full test coverage

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 johnbox codes
+
+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,248 @@
+# boxlogger
+
+A lightweight, Sentry-compatible backend logger with pluggable storage providers for Node.js applications.
+
+## Features
+
+- 🔌 **Pluggable Storage** - SQLite, Memory, or custom providers
+- 🎯 **Sentry-Compatible API** - Drop-in replacement for common Sentry functions
+- 📊 **Session Tracking** - Track user sessions with crash detection
+- 🔍 **Transaction Support** - Performance monitoring with custom measurements
+- 🍞 **Breadcrumbs** - Event trail for debugging
+- 🏷️ **Scoped Context** - Isolated logging contexts with tags and metadata
+- 💾 **Persistent Storage** - SQLite backend for production use
+- 🧪 **Fully Tested** - Comprehensive test coverage
+
+## Installation
+
+```bash
+npm install @johnboxcodes/boxlogger
+```
+
+For SQLite support:
+```bash
+npm install @johnboxcodes/boxlogger better-sqlite3
+```
+
+## Quick Start
+
+```typescript
+import * as Sentry from '@johnboxcodes/boxlogger';
+
+// Initialize with SQLite
+await Sentry.init('sqlite', { 
+  filename: './logs.db',
+  service: 'my-api',
+  environment: 'production'
+});
+
+// Capture errors
+try {
+  await riskyOperation();
+} catch (error) {
+  Sentry.captureException(error, {
+    tags: { section: 'payment' },
+    extra: { userId: '123' }
+  });
+}
+
+// Log messages
+Sentry.captureMessage('Payment processed', 'info');
+
+// Set user context
+Sentry.setUser({ id: '123', email: 'user@example.com' });
+
+// Add breadcrumbs
+Sentry.addBreadcrumb({
+  category: 'navigation',
+  message: 'User navigated to checkout',
+  level: 'info'
+});
+```
+
+## Storage Providers
+
+### SQLite (Recommended for Production)
+
+```typescript
+import * as Sentry from '@johnboxcodes/boxlogger';
+
+await Sentry.init('sqlite', {
+  filename: './logs.db',
+  service: 'my-service',
+  environment: 'production',
+  minLevel: 'info'
+});
+```
+
+### Memory (Development/Testing)
+
+```typescript
+await Sentry.init('memory', {
+  service: 'my-service',
+  environment: 'development',
+  minLevel: 'debug'
+});
+```
+
+### Custom Provider
+
+```typescript
+import { create } from 'boxlogger';
+import { MyCustomStore } from './my-store';
+
+const logger = await create(new MyCustomStore(), {
+  service: 'my-service'
+});
+```
+
+## API Reference
+
+### Core Functions
+
+#### `init(provider, options)`
+Initialize the logger with a storage provider.
+
+```typescript
+await Sentry.init('sqlite', {
+  filename: './logs.db',
+  service: 'my-api',
+  environment: 'production',
+  release: '1.0.0',
+  minLevel: 'info',
+  ignoreErrors: [/NetworkError/],
+  sampleRate: 1.0,
+  beforeSend: (event) => event
+});
+```
+
+#### `captureException(error, context?)`
+Capture and log exceptions with optional context.
+
+```typescript
+Sentry.captureException(error, {
+  tags: { section: 'api' },
+  extra: { endpoint: '/users' },
+  level: 'error',
+  user: { id: '123' }
+});
+```
+
+#### `captureMessage(message, level?)`
+Log custom messages.
+
+```typescript
+Sentry.captureMessage('User action completed', 'info');
+Sentry.captureMessage('Warning: High memory usage', {
+  level: 'warning',
+  tags: { component: 'memory-monitor' }
+});
+```
+
+#### `setUser(user)`
+Set user context for all subsequent logs.
+
+```typescript
+Sentry.setUser({
+  id: '123',
+  email: 'user@example.com',
+  username: 'john_doe',
+  ip_address: '{{auto}}'
+});
+```
+
+#### `addBreadcrumb(breadcrumb)`
+Add breadcrumb for event trail.
+
+```typescript
+Sentry.addBreadcrumb({
+  category: 'http',
+  message: 'API request',
+  level: 'info',
+  data: { url: '/api/users', method: 'GET' }
+});
+```
+
+#### `withScope(callback)`
+Execute code with isolated logging context.
+
+```typescript
+Sentry.withScope((scope) => {
+  scope.setTag('transaction', 'payment');
+  scope.setExtra('orderId', '12345');
+  Sentry.captureException(error);
+});
+```
+
+### Session Management
+
+```typescript
+// Start session
+await Sentry.startSession({ user: { id: '123' } });
+
+// End session
+await Sentry.endSession('ended');
+
+// Get current session
+const session = Sentry.getCurrentSession();
+```
+
+### Transaction Tracking
+
+```typescript
+const transaction = Sentry.startTransaction({
+  name: 'payment-processing',
+  op: 'payment'
+});
+
+transaction.setTag('payment-method', 'credit-card');
+transaction.setMeasurement('amount', 99.99, 'usd');
+transaction.setStatus('ok');
+transaction.finish();
+```
+
+### Query Logs
+
+```typescript
+// Get logs with filters
+const logs = await Sentry.getLogs({
+  level: 'error',
+  startTime: new Date('2024-01-01'),
+  limit: 100
+});
+
+// Get sessions
+const sessions = await Sentry.getSessions({
+  status: 'crashed'
+});
+
+// Get statistics
+const stats = await Sentry.getStats();
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `service` | `string` | - | Service name |
+| `environment` | `string` | `'production'` | Environment (production, development, etc.) |
+| `release` | `string` | - | Release version |
+| `minLevel` | `LogLevel` | `'info'` | Minimum log level |
+| `ignoreErrors` | `(string\|RegExp)[]` | `[]` | Errors to ignore |
+| `sampleRate` | `number` | `1.0` | Error sampling rate (0-1) |
+| `messagesSampleRate` | `number` | `1.0` | Message sampling rate (0-1) |
+| `beforeSend` | `function` | - | Hook to modify/filter events |
+| `beforeSendMessage` | `function` | - | Hook to modify/filter messages |
+
+## Examples
+
+See the [examples](./examples) directory for complete examples:
+- [examples/server.ts](./examples/server.ts) - Express server with error tracking
+
+## License
+
+MIT
+
+## Author
+
+johnbox codes