trmnl-cli 0.1.0

package/src/lib/validator.ts

@@ -0,0 +1,116 @@
+/**
+ * Payload validation for TRMNL webhooks
+ */
+
+import { TIER_LIMITS, type ValidationResult, type WebhookPayload, type WebhookTier } from '../types.ts';
+
+/**
+ * Validate a webhook payload against size limits
+ */
+export function validatePayload(payload: WebhookPayload, tier: WebhookTier = 'free'): ValidationResult {
+  const jsonString = JSON.stringify(payload);
+  const sizeBytes = new TextEncoder().encode(jsonString).length;
+  const limitBytes = TIER_LIMITS[tier];
+  const remainingBytes = limitBytes - sizeBytes;
+  const percentUsed = Math.round((sizeBytes / limitBytes) * 1000) / 10;
+
+  const warnings: string[] = [];
+  const errors: string[] = [];
+
+  // Size check
+  if (sizeBytes > limitBytes) {
+    errors.push(`Payload exceeds ${tier} tier limit: ${sizeBytes} bytes > ${limitBytes} bytes`);
+  } else if (percentUsed > 90) {
+    warnings.push(`Payload is at ${percentUsed}% of ${tier} tier limit`);
+  }
+
+  // Content check
+  if (!payload.merge_variables) {
+    errors.push('Missing merge_variables object');
+  } else if (!payload.merge_variables.content && !payload.merge_variables.text) {
+    warnings.push('No content or text field in merge_variables');
+  }
+
+  // HTML sanity checks
+  const content = payload.merge_variables?.content || '';
+  if (content) {
+    // Check for unclosed tags (basic check)
+    const openDivs = (content.match(/<div/g) || []).length;
+    const closeDivs = (content.match(/<\/div>/g) || []).length;
+    if (openDivs !== closeDivs) {
+      warnings.push(`Potential unclosed divs: ${openDivs} open, ${closeDivs} close`);
+    }
+
+    // Check for common TRMNL patterns - look for 'layout' as a class (may have other classes too)
+    const hasLayoutClass = /class=["'][^"']*\blayout\b[^"']*["']/.test(content);
+    if (!hasLayoutClass) {
+      warnings.push('Missing .layout class - TRMNL requires a root layout element');
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    size_bytes: sizeBytes,
+    tier,
+    limit_bytes: limitBytes,
+    remaining_bytes: remainingBytes,
+    percent_used: percentUsed,
+    warnings,
+    errors,
+  };
+}
+
+/**
+ * Parse content into a webhook payload
+ */
+export function createPayload(content: string): WebhookPayload {
+  // Try to parse as JSON first
+  try {
+    const parsed = JSON.parse(content);
+    if (parsed.merge_variables) {
+      return parsed as WebhookPayload;
+    }
+    // If it's just merge_variables content
+    return { merge_variables: parsed };
+  } catch {
+    // Treat as raw HTML content
+    return {
+      merge_variables: {
+        content: content,
+      },
+    };
+  }
+}
+
+/**
+ * Format validation result for display
+ */
+export function formatValidation(result: ValidationResult): string {
+  const lines: string[] = [];
+  
+  const status = result.valid ? '✓' : '✗';
+  const sizeKb = (result.size_bytes / 1024).toFixed(2);
+  const limitKb = (result.limit_bytes / 1024).toFixed(2);
+  
+  lines.push(`${status} Payload: ${result.size_bytes} bytes (${sizeKb} KB)`);
+  lines.push(`  Tier: ${result.tier} (limit: ${limitKb} KB)`);
+  lines.push(`  Used: ${result.percent_used}% (${result.remaining_bytes} bytes remaining)`);
+  
+  if (result.errors.length > 0) {
+    lines.push('');
+    lines.push('Errors:');
+    for (const error of result.errors) {
+      lines.push(`  ✗ ${error}`);
+    }
+  }
+  
+  if (result.warnings.length > 0) {
+    lines.push('');
+    lines.push('Warnings:');
+    for (const warning of result.warnings) {
+      lines.push(`  ⚠ ${warning}`);
+    }
+  }
+  
+  return lines.join('\n');
+}

package/src/lib/webhook.ts

@@ -0,0 +1,167 @@
+/**
+ * Webhook sending logic
+ */
+
+import { getTier, getWebhookUrl } from './config.ts';
+import { logEntry } from './logger.ts';
+import { validatePayload } from './validator.ts';
+import type { HistoryEntry, WebhookPayload, WebhookTier } from '../types.ts';
+
+export interface SendResult {
+  success: boolean;
+  pluginName: string;
+  statusCode?: number;
+  response?: string;
+  error?: string;
+  durationMs: number;
+  validation: ReturnType<typeof validatePayload>;
+}
+
+export interface SendOptions {
+  plugin?: string;        // Plugin name to use
+  webhookUrl?: string;    // Direct URL override
+  skipValidation?: boolean;
+  skipLog?: boolean;
+}
+
+/**
+ * Send payload to TRMNL webhook
+ */
+export async function sendToWebhook(
+  payload: WebhookPayload,
+  options: SendOptions = {}
+): Promise<SendResult> {
+  const startTime = Date.now();
+  const tier = getTier();
+  
+  // Resolve webhook URL
+  let webhookUrl: string;
+  let pluginName: string;
+
+  if (options.webhookUrl) {
+    // Direct URL override
+    webhookUrl = options.webhookUrl;
+    pluginName = 'custom';
+  } else {
+    // Get from config/env
+    const resolved = getWebhookUrl(options.plugin);
+    if (!resolved) {
+      const durationMs = Date.now() - startTime;
+      const validation = validatePayload(payload, tier);
+      
+      let error = 'No webhook URL configured.';
+      if (options.plugin) {
+        error = `Plugin "${options.plugin}" not found.`;
+      } else {
+        error += ' Add a plugin with: trmnl plugin add <name> <url>';
+      }
+      
+      return {
+        success: false,
+        pluginName: options.plugin || 'unknown',
+        error,
+        durationMs,
+        validation,
+      };
+    }
+    webhookUrl = resolved.url;
+    pluginName = resolved.name;
+  }
+
+  // Validate payload
+  const validation = validatePayload(payload, tier);
+  
+  if (!options.skipValidation && !validation.valid) {
+    const durationMs = Date.now() - startTime;
+    const result: SendResult = {
+      success: false,
+      pluginName,
+      error: validation.errors.join('; '),
+      durationMs,
+      validation,
+    };
+    
+    // Log failed validation
+    if (!options.skipLog) {
+      logEntry(createHistoryEntry(payload, result, tier, pluginName));
+    }
+    
+    return result;
+  }
+  
+  // Send request
+  try {
+    const response = await fetch(webhookUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(payload),
+    });
+    
+    const durationMs = Date.now() - startTime;
+    const responseText = await response.text();
+    
+    const result: SendResult = {
+      success: response.ok,
+      pluginName,
+      statusCode: response.status,
+      response: responseText,
+      durationMs,
+      validation,
+    };
+    
+    if (!response.ok) {
+      result.error = `HTTP ${response.status}: ${responseText}`;
+    }
+    
+    // Log the send
+    if (!options.skipLog) {
+      logEntry(createHistoryEntry(payload, result, tier, pluginName));
+    }
+    
+    return result;
+    
+  } catch (err) {
+    const durationMs = Date.now() - startTime;
+    const error = err instanceof Error ? err.message : 'Unknown error';
+    
+    const result: SendResult = {
+      success: false,
+      pluginName,
+      error,
+      durationMs,
+      validation,
+    };
+    
+    // Log the error
+    if (!options.skipLog) {
+      logEntry(createHistoryEntry(payload, result, tier, pluginName));
+    }
+    
+    return result;
+  }
+}
+
+/**
+ * Create a history entry from send result
+ */
+function createHistoryEntry(
+  payload: WebhookPayload,
+  result: SendResult,
+  tier: WebhookTier,
+  pluginName: string
+): HistoryEntry {
+  return {
+    timestamp: new Date().toISOString(),
+    plugin: pluginName,
+    size_bytes: result.validation.size_bytes,
+    tier,
+    payload,
+    success: result.success,
+    status_code: result.statusCode,
+    response: result.response,
+    error: result.error,
+    duration_ms: result.durationMs,
+  };
+}

package/src/types.ts

@@ -0,0 +1,80 @@
+/**
+ * TRMNL CLI Types
+ */
+
+/** Webhook tier determines payload size limits */
+export type WebhookTier = 'free' | 'plus';
+
+/** Size limits per tier in bytes */
+export const TIER_LIMITS: Record<WebhookTier, number> = {
+  free: 2048,   // 2 KB
+  plus: 5120,   // 5 KB
+};
+
+/** Plugin configuration */
+export interface Plugin {
+  url: string;
+  description?: string;
+}
+
+/** CLI configuration stored in ~/.trmnl/config.json */
+export interface Config {
+  plugins: Record<string, Plugin>;
+  defaultPlugin?: string;
+  tier?: WebhookTier;  // Global tier setting
+  history?: {
+    path?: string;
+    maxSizeMb?: number;
+  };
+}
+
+/** Default config values */
+export const DEFAULT_CONFIG: Config = {
+  plugins: {},
+  defaultPlugin: undefined,
+  tier: 'free',
+  history: {
+    path: '~/.trmnl/history.jsonl',
+    maxSizeMb: 100,
+  },
+};
+
+/** Merge variables payload structure */
+export interface MergeVariables {
+  content?: string;
+  title?: string;
+  text?: string;
+  image?: string;
+  [key: string]: string | undefined;
+}
+
+/** Webhook request payload */
+export interface WebhookPayload {
+  merge_variables: MergeVariables;
+}
+
+/** History entry stored in JSONL */
+export interface HistoryEntry {
+  timestamp: string;
+  plugin: string;
+  size_bytes: number;
+  tier: WebhookTier;
+  payload: WebhookPayload;
+  success: boolean;
+  status_code?: number;
+  response?: string;
+  error?: string;
+  duration_ms: number;
+}
+
+/** Validation result */
+export interface ValidationResult {
+  valid: boolean;
+  size_bytes: number;
+  tier: WebhookTier;
+  limit_bytes: number;
+  remaining_bytes: number;
+  percent_used: number;
+  warnings: string[];
+  errors: string[];
+}