{"_id":"@deer-management-company/metrics-client","name":"@deer-management-company/metrics-client","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@deer-management-company/metrics-client","version":"1.0.0","description":"TypeScript client for the Metabase Self-Hosted Metrics API","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build","example:basic":"ts-node examples/basic-usage.ts","example:express":"ts-node examples/express-example.ts"},"keywords":["metrics","monitoring","observability","metabase","analytics","typescript","sdk","client"],"author":{"name":"Deer Management Company"},"license":"MIT","dependencies":{"axios":"^1.6.0"},"devDependencies":{"@types/express":"^4.17.21","@types/jest":"^29.5.8","@types/node":"^20.8.10","@typescript-eslint/eslint-plugin":"^6.10.0","@typescript-eslint/parser":"^6.10.0","eslint":"^8.53.0","express":"^4.18.2","jest":"^29.7.0","ts-jest":"^29.1.1","ts-node":"^10.9.1","typescript":"^5.2.2"},"peerDependencies":{"express":"^4.0.0"},"peerDependenciesMeta":{"express":{"optional":true}},"engines":{"node":">=16.0.0","npm":">=7.0.0"},"repository":{"type":"git","url":"git+https://github.com/deer-management-company/metabase-self-hosted.git","directory":"sdk/typescript"},"bugs":{"url":"https://github.com/deer-management-company/metabase-self-hosted/issues"},"homepage":"https://github.com/deer-management-company/metabase-self-hosted#readme","_id":"@deer-management-company/metrics-client@1.0.0","gitHead":"46c5654f68c309b31e77840ede22e404d4eb5fe7","_nodeVersion":"23.10.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-z4ocQdtDe35Rx1c1uGyVthdntou+4tEe58xzpL48CsFOdJKq0iZGQp8zxmze50B443sfxTOkZg6W55BF/cMnlA==","shasum":"5b3ee379adc7a3c611b2306592763c0ee3d80f01","tarball":"https://registry.npmjs.org/@deer-management-company/metrics-client/-/metrics-client-1.0.0.tgz","fileCount":18,"unpackedSize":50314,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDqS3EkoCZv2SqkND/y8mnJn8+z6UoG+zBVZ4DmdKmZpQIgAIVl8+wlUCKnCnbhlL5N/6tR5aQEt5cS9nO5vmiee+4="}]},"_npmUser":{"name":"sf-brain-integration","email":"thaalesheenrique@gmail.com"},"directories":{},"maintainers":[{"name":"sf-brain-integration","email":"thaalesheenrique@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/metrics-client_1.0.0_1757432030927_0.22926059480939642"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-09T15:33:50.877Z","1.0.0":"2025-09-09T15:33:51.123Z","modified":"2025-09-09T15:33:51.395Z"},"maintainers":[{"name":"sf-brain-integration","email":"thaalesheenrique@gmail.com"}],"description":"TypeScript client for the Metabase Self-Hosted Metrics API","homepage":"https://github.com/deer-management-company/metabase-self-hosted#readme","keywords":["metrics","monitoring","observability","metabase","analytics","typescript","sdk","client"],"repository":{"type":"git","url":"git+https://github.com/deer-management-company/metabase-self-hosted.git","directory":"sdk/typescript"},"author":{"name":"Deer Management Company"},"bugs":{"url":"https://github.com/deer-management-company/metabase-self-hosted/issues"},"license":"MIT","readme":"# @deer-management-company/metrics-client\n\nTypeScript client for the Metabase Self-Hosted Metrics API. A powerful and type-safe SDK for collecting and sending metrics, job execution data, and API logs to your self-hosted monitoring infrastructure.\n\n## 🚀 Installation\n\n```bash\nnpm install @deer-management-company/metrics-client\n```\n\n## 📋 Quick Start\n\n```typescript\nimport { MetricsClient } from '@deer-management-company/metrics-client';\n\n// Initialize the client\nconst metricsClient = new MetricsClient({\n\tbaseUrl: 'http://your-metrics-api:3002',\n\tapiKey: 'your-api-key',\n\tserviceName: 'your-service-name',\n\tenvironment: 'production'\n});\n\n// Record a job execution\nawait metricsClient.recordJob({\n\tjob_name: 'newsletter',\n\tstatus: 'success',\n\ttotal_results: 1250,\n\texecution_time_ms: 45000,\n\tmetrics: {\n\t\tqtd_save: 67,\n\t\tqtd_rejected: 22\n\t}\n});\n\n// Record API calls\nawait metricsClient.recordApiCall({\n\tendpoint: '/api/users',\n\tmethod: 'GET',\n\tstatus_code: 200,\n\tresponse_time_ms: 145\n});\n\n// Record performance metrics\nawait metricsClient.recordMetric({\n\tmetric_name: 'cpu_usage_percent',\n\tmetric_value: 45.6,\n\tmetric_type: 'gauge',\n\tlabels: {\n\t\tinstance: 'web-01'\n\t}\n});\n```\n\n## 🔧 Express.js Integration\n\n```typescript\nimport express from 'express';\nimport { createMetricsMiddleware, createMetricsClient } from '@deer-management-company/metrics-client';\n\nconst app = express();\nconst metricsClient = createMetricsClient({\n\tbaseUrl: 'http://your-metrics-api:3002',\n\tapiKey: 'your-api-key',\n\tserviceName: 'express-api'\n});\n\n// Add metrics middleware\napp.use(createMetricsMiddleware(metricsClient));\n\n// Your routes here\napp.get('/api/users', (req, res) => {\n\tres.json({ users: [] });\n});\n```\n\n## 📊 Temporal Integration\n\nPerfect for monitoring Temporal workflows:\n\n```typescript\nimport { MetricsClient } from '@deer-management-company/metrics-client';\n\n@Workflow()\nexport class NewsletterWorkflow {\n\tasync runNewsletter(params: NewsletterParams): Promise<NewsletterResult> {\n\t\tconst metricsClient = new MetricsClient({\n\t\t\tbaseUrl: 'http://localhost:3002',\n\t\t\tapiKey: process.env.METRICS_API_KEY!,\n\t\t\tserviceName: 'temporal-newsletter'\n\t\t});\n\n\t\tconst startTime = Date.now();\n\n\t\ttry {\n\t\t\tconst result = await Activity.runNewsletterActivity(params);\n\n\t\t\t// Record successful execution\n\t\t\tawait metricsClient.recordJob({\n\t\t\t\tjob_name: 'newsletter',\n\t\t\t\tstatus: 'success',\n\t\t\t\ttotal_results: result.totalEmails,\n\t\t\t\texecution_time_ms: Date.now() - startTime,\n\t\t\t\tmetrics: {\n\t\t\t\t\tqtd_save: result.saved,\n\t\t\t\t\tqtd_rejected: result.rejected,\n\t\t\t\t\tqtd_sent: result.sent\n\t\t\t\t}\n\t\t\t});\n\n\t\t\treturn result;\n\t\t} catch (error) {\n\t\t\t// Record failure\n\t\t\tawait metricsClient.recordJob({\n\t\t\t\tjob_name: 'newsletter',\n\t\t\t\tstatus: 'failed',\n\t\t\t\texecution_time_ms: Date.now() - startTime,\n\t\t\t\terror_message: error.message\n\t\t\t});\n\n\t\t\tthrow error;\n\t\t}\n\t}\n}\n```\n\n## 📖 API Reference\n\n### MetricsClient\n\n#### Constructor\n\n```typescript\nnew MetricsClient(config: MetricsClientConfig, options?: MetricsClientOptions)\n```\n\n#### Methods\n\n##### Job Tracking\n\n-   `recordJob(jobMetric: JobMetric)` - Record job execution\n-   `getJobMetrics(jobName: string)` - Get aggregated job metrics\n-   `getJobHistory(jobName: string, options?)` - Get job execution history\n\n##### API Monitoring\n\n-   `recordApiCall(apiLog: ApiLogData)` - Record API call\n-   `getApiLogs(options?)` - Get API call logs\n\n##### Performance Metrics\n\n-   `recordMetric(metric: PerformanceMetric)` - Record single metric\n-   `recordMetricsBatch(metrics: PerformanceMetric[])` - Record multiple metrics\n\n##### Utility Methods\n\n-   `healthCheck()` - Check API health\n-   `getServiceHealth()` - Get service health status\n-   `getSystemStatus()` - Get overall system status\n\n##### Metric Helpers\n\n-   `counter(name: string, labels?: object)` - Create counter metric\n-   `gauge(name: string, labels?: object)` - Create gauge metric\n-   `histogram(name: string, labels?: object)` - Create histogram metric\n-   `timeFunction(name: string, fn: Function, options?)` - Time function execution\n\n### Configuration\n\n```typescript\ninterface MetricsClientConfig {\n\tbaseUrl: string; // API base URL\n\tapiKey: string; // API authentication key\n\tserviceName: string; // Your service identifier\n\ttimeout?: number; // Request timeout (default: 5000)\n\tretries?: number; // Retry attempts (default: 3)\n\tenvironment?: string; // Environment (default: 'production')\n}\n\ninterface MetricsClientOptions {\n\ttimeout?: number; // Request timeout\n\tretries?: number; // Retry attempts\n\tretryDelay?: number; // Delay between retries\n\tuserAgent?: string; // Custom user agent\n\tenableDebug?: boolean; // Enable debug logging\n}\n```\n\n### Data Types\n\n```typescript\ninterface JobMetric {\n\tjob_name: string;\n\tservice_name: string;\n\tuser_name?: string;\n\tstatus: 'success' | 'failed' | 'pending';\n\ttotal_results?: number;\n\texecution_time_ms?: number;\n\tmetrics?: Record<string, any>;\n\terror_message?: string;\n\tenvironment?: string;\n}\n\ninterface ApiLogData {\n\tservice_name: string;\n\tendpoint: string;\n\tmethod: string;\n\tstatus_code?: number;\n\tresponse_time_ms?: number;\n\terror_type?: string;\n\terror_message?: string;\n\trequest_id?: string;\n\tuser_id?: string;\n\tmetadata?: Record<string, any>;\n\tenvironment?: string;\n}\n\ninterface PerformanceMetric {\n\tservice_name: string;\n\tmetric_name: string;\n\tmetric_value: number;\n\tmetric_type?: 'counter' | 'gauge' | 'histogram';\n\tlabels?: Record<string, any>;\n}\n```\n\n## 🎯 Use Cases\n\n### Newsletter Monitoring\n\n```typescript\n// Track newsletter job execution\nawait metricsClient.recordJob({\n\tjob_name: 'newsletter',\n\tstatus: 'success',\n\ttotal_results: 1250,\n\texecution_time_ms: 45000,\n\tmetrics: {\n\t\tqtd_save: 67,\n\t\tqtd_rejected: 22,\n\t\tsuccess_rate: 75.28\n\t}\n});\n```\n\n### API Performance Tracking\n\n```typescript\n// Track API endpoint performance\nawait metricsClient.recordApiCall({\n\tendpoint: '/api/v1/users',\n\tmethod: 'GET',\n\tstatus_code: 200,\n\tresponse_time_ms: 145,\n\tuser_id: 'user123'\n});\n```\n\n### System Metrics Collection\n\n```typescript\n// Track system performance\nawait metricsClient.recordMetric({\n\tmetric_name: 'cpu_usage_percent',\n\tmetric_value: 45.6,\n\tmetric_type: 'gauge',\n\tlabels: {\n\t\tinstance: 'web-01',\n\t\tregion: 'us-east-1'\n\t}\n});\n```\n\n## 🔗 Related Projects\n\n-   [Metabase Self-Hosted](https://github.com/deer-management-company/metabase-self-hosted) - Complete monitoring solution\n-   [Temporal](https://temporal.io/) - Workflow orchestration platform\n\n## 🛠 Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run in development mode\nnpm run dev\n\n# Run tests\nnpm run test\n\n# Run linting\nnpm run lint\n\n# Fix linting issues\nnpm run lint:fix\n```\n\n## 📄 License\n\nMIT License - see LICENSE file for details.\n\n## 🤝 Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Run linting and tests\n6. Submit a pull request\n\n## 🐛 Issues\n\nFound a bug? Please [open an issue](https://github.com/deer-management-company/metabase-self-hosted/issues) with:\n\n-   Description of the issue\n-   Steps to reproduce\n-   Expected vs actual behavior\n-   Environment details\n\n---\n\nBuilt with ❤️ by [Deer Management Company](https://github.com/deer-management-company)\n","readmeFilename":"README.md","_rev":"1-a1b9ee81008a3103696114fb4518017c"}