feat: initial release v0.1.0 — Send minimalist homelab alerts with ASCII sparklines to Discord/Slack.

Author: AdametherzLab

.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+.env
+.env.local
+*.log
+.DS_Store
+Thumbs.db
+coverage/
+.turbo/
+*.tsbuildinfo

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AdametherzLab
+
+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.

README.md

@@ -0,0 +1,202 @@
+# webhook-spark ⚡
+
+**Send minimalist homelab alerts with ASCII sparklines to Discord/Slack**
+
+## ✨ Features
+
+- 📊 **Beautiful ASCII sparklines** – Turn boring number arrays into visual trends
+- 🔌 **Webhook support** – Discord and Slack out of the box
+- 🚀 **Zero dependencies** – Uses only Node.js/Bun built-ins
+- 📦 **Tiny footprint** – Less than 10KB minified
+- 🛡️ **TypeScript first** – Full type safety and autocomplete
+- 🎨 **Customizable** – Multiple character sets and styling options
+
+## 📦 Installation
+
+```bash
+# Using Bun (recommended)
+bun add webhook-spark
+
+# Using npm
+npm install webhook-spark
+
+# Using yarn
+yarn add webhook-spark
+```
+
+## 🚀 Quick Start
+
+```typescript
+// REMOVED external import: import { generateSparkline, sendWebhook } from 'webhook-spark';
+
+// Create a sparkline from your metrics
+const cpuUsage = [10, 25, 60, 85, 90, 45, 30];
+const sparkline = generateSparkline(cpuUsage);
+
+// Send to Discord
+await sendWebhook({
+  url: 'https://discord.com/api/webhooks/your-webhook-id',
+  provider: 'discord',
+  content: `CPU usage: ${sparkline}`,
+  username: 'Server Monitor'
+});
+
+console.log(`📈 Sparkline sent: ${sparkline}`);
+// Output: 📈 Sparkline sent: ▁▂▅▇██▃▂
+```
+
+## 📖 API Reference
+
+### Sparkline Generation
+
+```typescript
+// REMOVED external import: import { generateSparkline, generateSparklineWithOutliers } from 'webhook-spark';
+
+// Basic sparkline
+const sparkline = generateSparkline([1, 2, 3, 4, 5]);
+// Returns: ▁▂▃▄▅
+
+// With custom options
+const custom = generateSparkline([10, 50, 90], {
+  characterSet: '·∙●○◉◎',
+  minValue: 0,
+  maxValue: 100
+});
+
+// Handle outliers
+const withOutliers = generateSparklineWithOutliers(
+  [1, 1000, 2, 3, 4],
+  { threshold: 2 } // Values > 2 standard deviations marked
+);
+```
+
+### Webhook Delivery
+
+```typescript
+// REMOVED external import: import { sendWebhook } from 'webhook-spark';
+
+// Discord example
+await sendWebhook({
+  url: 'DISCORD_WEBHOOK_URL',
+  provider: 'discord',
+  content: 'Server alert!',
+  embeds: [{
+    title: 'CPU Usage',
+    description: generateSparkline([10, 25, 60, 85]),
+    color: 0xff0000,
+    timestamp: new Date().toISOString()
+  }]
+});
+
+// Slack example
+await sendWebhook({
+  url: 'SLACK_WEBHOOK_URL',
+  provider: 'slack',
+  content: 'Daily metrics',
+  blocks: [{
+    type: 'section',
+    text: { type: 'mrkdwn', text: `*Memory usage:* ${generateSparkline([30, 45, 60])}` }
+  }]
+});
+```
+
+### Type Utilities
+
+```typescript
+// REMOVED external import: import { isNumericArray, isWebhookConfig } from 'webhook-spark';
+
+// Type guards for validation
+if (isNumericArray(data)) {
+  // data is now typed as readonly number[]
+  const sparkline = generateSparkline(data);
+}
+
+const config = { url: '...', provider: 'discord' };
+if (isWebhookConfig(config)) {
+  // config is valid WebhookConfig
+  await sendWebhook(config);
+}
+```
+
+## 🧪 Examples
+
+### Homelab CPU Monitor
+
+```typescript
+// REMOVED external import: import { generateSparkline, sendWebhook } from 'webhook-spark';
+import os from 'os';
+
+// Simulate collecting CPU metrics
+const cpuMetrics = [45, 60, 75, 85, 90, 80, 65];
+const sparkline = generateSparkline(cpuMetrics);
+
+// Send alert if high usage
+if (cpuMetrics[cpuMetrics.length - 1] > 80) {
+  await sendWebhook({
+    url: process.env.DISCORD_WEBHOOK!,
+    provider: 'discord',
+    content: `🚨 High CPU usage detected!`,
+    embeds: [{
+      title: 'CPU Trend',
+      description: `\`${sparkline}\``,
+      fields: [
+        { name: 'Current', value: `${cpuMetrics[cpuMetrics.length - 1]}%`, inline: true },
+        { name: 'Peak', value: `${Math.max(...cpuMetrics)}%`, inline: true }
+      ],
+      color: 0xff5500
+    }]
+  });
+}
+```
+
+### Daily Health Report
+
+```typescript
+// REMOVED external import: import { generateSparkline, generateASCIIArt } from 'webhook-spark';
+
+// Create a dashboard-like report
+const report = `
+📊 **Daily System Report**
+━━━━━━━━━━━━━━━━━━━━
+CPU:    ${generateSparkline([10, 25, 40, 60, 45, 30])}
+Memory: ${generateSparkline([50, 55, 60, 65, 70, 68])}
+Disk:   ${generateSparkline([85, 86, 87, 88, 89, 90])}
+
+${generateASCIIArt('HEALTHY', { font: 'block' })}
+`;
+
+await sendWebhook({
+  url: process.env.SLACK_WEBHOOK!,
+  provider: 'slack',
+  content: report
+});
+```
+
+## 🔧 Configuration
+
+```json
+{
+  "defaultWebhook": "https://discord.com/api/webhooks/your-id",
+  "defaultProvider": "discord",
+  "dataDir": "~/.webhook-spark/data",
+  "maxEntries": 1000
+}
+```
+
+## 🤝 Contributing
+
+Found a bug? Have an idea for a new feature? Contributions are welcome!
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b cool-new-feature`)
+3. Commit your changes (`git commit -am 'Add cool feature'`)
+4. Push to the branch (`git push origin cool-new-feature`)
+5. Open a Pull Request
+
+## 📄 License
+
+MIT © AdametherzLab
+
+---
+
+Made with ⚡ by homelab enthusiasts for homelab enthusiasts. Keep your servers happy and your alerts beautiful!

SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in this project, please report it responsibly.
+
+**Contact:** security@adametherzlab.com
+
+**Process:**
+1. Email the details of the vulnerability
+2. Include steps to reproduce if possible
+3. We will acknowledge your report within 48 hours
+4. We aim to fix critical issues within 7 days
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.x.x   | Yes       |
+
+## Disclosure Policy
+
+- We follow responsible disclosure practices
+- Please do not publicly disclose vulnerabilities before they are fixed
+- We will credit reporters in our release notes (unless you prefer anonymity)

package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@adametherzlab/webhook-spark",
+  "version": "0.1.0",
+  "description": "Send minimalist homelab alerts with ASCII sparklines to Discord/Slack.",
+  "type": "module",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "bun build src/index.ts --outdir dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.5.0"
+  },
+  "keywords": [
+    "typescript",
+    "bun",
+    "homelab",
+    "devops",
+    "monitoring",
+    "discord-webhook",
+    "cli"
+  ],
+  "author": "AdametherzLab",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AdametherzLab/webhook-spark.git"
+  },
+  "homepage": "https://github.com/AdametherzLab/webhook-spark#readme",
+  "bugs": {
+    "url": "https://github.com/AdametherzLab/webhook-spark/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false
+}

src/index.ts

@@ -0,0 +1,51 @@
+import type {
+  SparklineConfig,
+  SparklineCharacterSet,
+  ASCIIArtConfig,
+  WebhookPayload,
+  WebhookResponse,
+  WebhookConfig,
+  ValidationError,
+  WebhookError,
+  NumericArray,
+  WebhookSendResult,
+  SparklineGenerationResult,
+  ConfigFile,
+  DiscordEmbed,
+  SlackBlock,
+  HttpMethod,
+  HttpRequestOptions,
+  WebhookProvider,
+} from "./types.js";
+import { generateSparkline, generateSparklineWithOutliers, generateASCIIArt } from "./sparkline.js";
+import { sendWebhook } from "./webhook.js";
+import { isNumericArray, isSparklineConfig, isWebhookConfig } from "./types.js";
+
+export {
+  generateSparkline,
+  generateSparklineWithOutliers,
+  generateASCIIArt,
+  sendWebhook,
+  isNumericArray,
+  isSparklineConfig,
+  isWebhookConfig,
+};
+export type {
+  SparklineConfig,
+  SparklineCharacterSet,
+  ASCIIArtConfig,
+  WebhookPayload,
+  WebhookResponse,
+  WebhookConfig,
+  ValidationError,
+  WebhookError,
+  NumericArray,
+  WebhookSendResult,
+  SparklineGenerationResult,
+  ConfigFile,
+  DiscordEmbed,
+  SlackBlock,
+  HttpMethod,
+  HttpRequestOptions,
+  WebhookProvider,
+};