{"id":43245726,"url":"https://github.com/checklogsdev/node-sdk","last_synced_at":"2026-02-01T12:09:51.108Z","repository":{"id":310719934,"uuid":"1040998530","full_name":"checklogsdev/node-sdk","owner":"checklogsdev","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-03T21:32:59.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-03T23:25:31.307Z","etag":null,"topics":["logs","node-sdk","panel","simple"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@checklogs/node-sdk","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/checklogsdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-19T20:33:09.000Z","updated_at":"2025-09-03T21:33:03.000Z","dependencies_parsed_at":"2025-09-03T23:16:56.737Z","dependency_job_id":null,"html_url":"https://github.com/checklogsdev/node-sdk","commit_stats":null,"previous_names":["checklogsdev/node-sdk"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/checklogsdev/node-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checklogsdev%2Fnode-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checklogsdev%2Fnode-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checklogsdev%2Fnode-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checklogsdev%2Fnode-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/checklogsdev","download_url":"https://codeload.github.com/checklogsdev/node-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checklogsdev%2Fnode-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28977778,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T11:31:13.034Z","status":"ssl_error","status_checked_at":"2026-02-01T11:30:25.558Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["logs","node-sdk","panel","simple"],"created_at":"2026-02-01T12:09:50.409Z","updated_at":"2026-02-01T12:09:51.102Z","avatar_url":"https://github.com/checklogsdev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @checklogs/node-sdk\n\nOfficial Node.js SDK for CheckLogs.dev - A powerful log monitoring system.\n\n## Installation\n\n```bash\nnpm install @checklogs/node-sdk\n```\n\n### Quick Start Setup\n\nFor a guided setup, you can use our quick-start script:\n\n```bash\nnpx @checklogs/node-sdk quick-start\n```\n\nThis will:\n- Detect your project type (CommonJS or ES Modules)\n- Create appropriate test files\n- Set up a basic configuration\n- Provide next steps to get you started\n\n## Quick Start\n\n### CommonJS (require)\n\n```javascript\nconst { createLogger } = require('@checklogs/node-sdk');\n\n// Create a logger instance\nconst logger = createLogger('your-api-key-here');\n\n// Log messages\nawait logger.info('Application started');\nawait logger.error('Something went wrong', { error_code: 500 });\n```\n\n### ES Modules (import)\n\n```javascript\nimport { createLogger } from '@checklogs/node-sdk';\n\n// Create a logger instance\nconst logger = createLogger('your-api-key-here');\n\n// Log messages\nawait logger.info('Application started');\nawait logger.error('Something went wrong', { error_code: 500 });\n```\n\n**Note**: The SDK supports both CommonJS and ES modules. Use the import/export syntax you prefer!\n\n## Module Support\n\nThis package supports both CommonJS and ES modules:\n\n- **CommonJS**: Use `require()` syntax - works in traditional Node.js projects\n- **ES Modules**: Use `import/export` syntax - works in modern Node.js projects with `\"type\": \"module\"` in package.json or `.mjs` files\n\nThe package automatically provides the correct format based on how you import it.\n\n## Features\n\n- ✅ Full API coverage (logging, retrieval, statistics)\n- ✅ Dual package support (CommonJS \u0026 ES Modules)\n- ✅ TypeScript support with complete type definitions\n- ✅ Automatic retry mechanism with exponential backoff\n- ✅ Enhanced logging with metadata (hostname, process info, timestamps)\n- ✅ Console output integration\n- ✅ Child loggers with inherited context\n- ✅ Statistics and analytics\n- ✅ Error handling with custom error types\n- ✅ Validation and sanitization\n\n## API Overview\n\n### Basic Client\n\n**CommonJS:**\n```javascript\nconst { CheckLogsClient } = require('@checklogs/node-sdk');\n\nconst client = new CheckLogsClient('your-api-key');\n```\n\n**ES Modules:**\n```javascript\nimport { CheckLogsClient } from '@checklogs/node-sdk';\n\nconst client = new CheckLogsClient('your-api-key');\n```\n\n**Usage:**\n```javascript\n// Send a log\nawait client.log({\n  message: 'User logged in',\n  level: 'info',\n  context: { user_id: 123, ip: '192.168.1.1' }\n});\n\n// Retrieve logs\nconst logs = await client.getLogs({\n  limit: 100,\n  level: 'error',\n  since: '2024-01-01'\n});\n```\n\n### Enhanced Logger\n\n**CommonJS:**\n```javascript\nconst { CheckLogsLogger } = require('@checklogs/node-sdk');\n```\n\n**ES Modules:**\n```javascript\nimport { CheckLogsLogger } from '@checklogs/node-sdk';\n```\n\n**Usage:**\n```javascript\nconst logger = new CheckLogsLogger('your-api-key', {\n  source: 'my-app',\n  defaultContext: { version: '1.0.0' },\n  consoleOutput: true\n});\n\n// Convenience methods\nawait logger.info('Info message');\nawait logger.warning('Warning message');\nawait logger.error('Error message');\nawait logger.critical('Critical message');\nawait logger.debug('Debug message');\n```\n\n## Configuration Options\n\n### Client Options\n\n```javascript\nconst client = new CheckLogsClient('api-key', {\n  timeout: 5000,           // Request timeout in ms\n  validatePayload: true    // Validate data before sending\n});\n```\n\n### Logger Options\n\n```javascript\nconst logger = new CheckLogsLogger('api-key', {\n  // Client options\n  timeout: 5000,\n  validatePayload: true,\n  \n  // Logger-specific options\n  source: 'my-app',                    // Default source\n  user_id: 123,                        // Default user ID\n  defaultContext: { env: 'prod' },     // Default context\n  silent: false,                       // Suppress all output\n  consoleOutput: true,                 // Also log to console\n  enabledLevels: ['info', 'error'],    // Only these levels\n  includeTimestamp: true,              // Add timestamp to context\n  includeHostname: true                // Add hostname to context\n});\n```\n\n## Advanced Features\n\n### Child Loggers\n\nCreate child loggers with inherited context:\n\n```javascript\nconst mainLogger = new CheckLogsLogger('api-key', {\n  defaultContext: { service: 'api' }\n});\n\nconst userLogger = mainLogger.child({ module: 'user' });\nconst orderLogger = mainLogger.child({ module: 'orders' });\n\n// Each child inherits parent context\nawait userLogger.info('User created');  // Context: { service: 'api', module: 'user' }\nawait orderLogger.error('Order failed'); // Context: { service: 'api', module: 'orders' }\n```\n\n### Timing Logs\n\nMeasure execution time:\n\n```javascript\nconst endTimer = logger.time('db-query', 'Executing database query');\n\n// ... your code here ...\n\nconst duration = endTimer(); // Automatically logs end time with duration\nconsole.log(`Operation took ${duration}ms`);\n```\n\n### Statistics and Analytics\n\n```javascript\n// Get basic statistics\nconst stats = await client.stats.getStats();\nconsole.log('Total logs:', stats.data.total_logs);\n\n// Get analytics summary\nconst summary = await client.stats.getSummary();\nconsole.log('Error rate:', summary.data.analytics.error_rate);\n\n// Get specific metrics\nconst errorRate = await client.stats.getErrorRate();\nconst trend = await client.stats.getTrend();\nconst peakDay = await client.stats.getPeakDay();\n```\n\n### Error Handling\n\nThe SDK provides specific error types:\n\n```javascript\nconst { ApiError, NetworkError, ValidationError } = require('@checklogs/node-sdk');\n\ntry {\n  await logger.log({ /* invalid data */ });\n} catch (error) {\n  if (error instanceof ValidationError) {\n    console.log('Validation failed:', error.message);\n  } else if (error instanceof ApiError) {\n    console.log('API error:', error.statusCode, error.message);\n    \n    if (error.isAuthError()) {\n      console.log('Authentication problem');\n    } else if (error.isRateLimitError()) {\n      console.log('Rate limit exceeded');\n    }\n  } else if (error instanceof NetworkError) {\n    console.log('Network problem:', error.message);\n    \n    if (error.isTimeoutError()) {\n      console.log('Request timed out');\n    }\n  }\n}\n```\n\n### Retry Mechanism\n\nThe logger automatically retries failed requests:\n\n```javascript\n// Check retry queue status\nconst status = logger.getRetryQueueStatus();\nconsole.log(`${status.count} logs pending retry`);\n\n// Wait for all logs to be sent\nconst success = await logger.flush(30000); // 30 second timeout\nif (success) {\n  console.log('All logs sent successfully');\n}\n\n// Clear retry queue if needed\nlogger.clearRetryQueue();\n```\n\n## Log Levels\n\nSupported log levels (in order of severity):\n\n- `debug` - Development and troubleshooting information\n- `info` - General application flow\n- `warning` - Potentially harmful situations\n- `error` - Error events that might still allow the application to continue\n- `critical` - Very severe error events that might cause the application to abort\n\n## Data Validation\n\nThe SDK automatically validates and sanitizes data:\n\n- **Message**: Required, max 1024 characters\n- **Level**: Must be valid level, defaults to 'info'\n- **Source**: Max 100 characters\n- **Context**: Objects only, max 5000 characters when serialized\n- **User ID**: Must be a number\n\n## Rate Limiting and Best Practices\n\n1. **Batch Operations**: Use child loggers for related operations\n2. **Level Filtering**: Only enable necessary log levels in production\n3. **Context Size**: Keep context objects reasonably small\n4. **Error Handling**: Always handle potential network issues\n5. **Graceful Shutdown**: Call `flush()` before app termination\n\n## TypeScript Support\n\nFull TypeScript definitions are included:\n\n```typescript\nimport { CheckLogsLogger, LogLevel, LogData } from '@checklogs/node-sdk';\n\nconst logger = new CheckLogsLogger('api-key');\n\nconst logData: LogData = {\n  message: 'User action',\n  level: 'info',\n  context: { userId: 123 }\n};\n\nawait logger.log(logData);\n```\n\n## Examples\n\n### Express.js Middleware\n\n**CommonJS version:**\n```javascript\nconst express = require('express');\nconst { createLogger } = require('@checklogs/node-sdk');\n\nconst app = express();\nconst logger = createLogger('your-api-key');\n\n// Request logging middleware\napp.use((req, res, next) =\u003e {\n  const requestLogger = logger.child({\n    request_id: Math.random().toString(36),\n    method: req.method,\n    url: req.url\n  });\n  \n  req.logger = requestLogger;\n  next();\n});\n\n// Route handler\napp.get('/users/:id', async (req, res) =\u003e {\n  try {\n    req.logger.info('Fetching user', { user_id: req.params.id });\n    \n    // ... your logic here ...\n    \n    req.logger.info('User fetched successfully');\n    res.json({ user: userData });\n  } catch (error) {\n    req.logger.error('Failed to fetch user', { \n      error: error.message,\n      stack: error.stack \n    });\n    res.status(500).json({ error: 'Internal server error' });\n  }\n});\n```\n\n**ES Modules version:**\n```javascript\nimport express from 'express';\nimport { createLogger } from '@checklogs/node-sdk';\n\nconst app = express();\nconst logger = createLogger('your-api-key');\n\n// ... rest of the code is identical ...\n```\n\n### Cron Job Monitoring\n\n```javascript\nconst { createLogger } = require('@checklogs/node-sdk');\n\nconst logger = createLogger('your-api-key', {\n  source: 'cron-job',\n  defaultContext: { job: 'daily-cleanup' }\n});\n\nasync function dailyCleanup() {\n  const endTimer = logger.time('cleanup', 'Starting daily cleanup');\n  \n  try {\n    logger.info('Cleanup started');\n    \n    // ... cleanup logic ...\n    \n    logger.info('Cleanup completed successfully', { \n      records_cleaned: 1500,\n      duration_ms: endTimer()\n    });\n  } catch (error) {\n    logger.critical('Cleanup failed', { \n      error: error.message,\n      duration_ms: endTimer()\n    });\n    throw error;\n  }\n}\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Support\n\n- Documentation: [https://docs.checklogs.dev](https://docs.checklogs.dev)\n- Issues: [GitHub Issues](https://github.com/checklogs/node-sdk/issues)\n- Email: support@checklogs.dev","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchecklogsdev%2Fnode-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchecklogsdev%2Fnode-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchecklogsdev%2Fnode-sdk/lists"}