lorentz/wulf-pulse
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
22 commits 2 branches 0 tags 15 MiB
Commit graph

8 commits

Author SHA1 Message Date
root
8e83347138 docs: add Pangolin tunnel setup guide for webhook endpoint 
User confirmed they use Pangolin (similar to Cloudflare Tunnel), so
created a comprehensive Pangolin-specific configuration guide.

Complete guide includes:
- Pangolin agent installation
- Tunnel configuration with path-based access control
- DNS setup
- Systemd service configuration
- Security settings (rate limiting, IP whitelisting)
- Testing procedures
- Troubleshooting guide
- Performance optimization
- High availability setup

Configuration features:
- Only /api/webhooks/autotask exposed
- Rate limiting: 100 req/min, burst 20
- Automatic SSL/TLS via Pangolin
- All other paths return 404
- No firewall changes needed
- No open ports required

Benefits over other approaches:
- No public IP needed
- Zero Trust security model
- Automatic DDoS protection
- Built-in load balancing
- Simple configuration

File: docs/WEBHOOK_PANGOLIN_SETUP.md
 2026-01-24 17:18:27 -05:00
root
80d8d40f06 docs: add reverse proxy configuration guide for webhook endpoint 
Since Pulse is not publicly accessible, added comprehensive guide for
exposing only the webhook endpoint to Autotask via reverse proxy.

Covers 4 approaches:
1. Nginx + Let's Encrypt (recommended for production)
2. Cloudflare Tunnel (easiest, no firewall changes)
3. Caddy (automatic HTTPS)
4. Traefik (for Docker users)

Each includes:
- Complete configuration examples
- Setup steps
- Security recommendations (rate limiting, IP whitelisting)
- Testing procedures
- Troubleshooting guides

Security features:
- Only /api/webhooks/autotask exposed
- SSL/TLS encryption required
- Rate limiting (100 req/min, burst 20)
- Optional IP whitelisting for Autotask
- All other paths return 404

File: docs/WEBHOOK_REVERSE_PROXY.md
 2026-01-24 17:14:55 -05:00
root
1f83456199 feat: add webhook support for real-time Autotask updates 
Implements comprehensive webhook infrastructure to receive and process
real-time entity updates from Autotask, reducing API calls and improving
data freshness.

Features:
- Webhook receiver endpoint: POST /api/webhooks/autotask
- Automatic entity mapping and upsert to PostgreSQL
- Event logging and tracking in webhook_logs table
- Duplicate event prevention via unique event_id
- Failed event tracking with error messages
- Statistics and monitoring APIs
- Support for 8 entity types: Companies, Tickets, Tasks, Projects,
  Time Entries, Contacts, Contracts, Configuration Items

Architecture:
- WebhookService: Core processing logic
- Database tables: webhook_logs, webhook_configs
- API endpoints: /autotask (receiver), /logs, /stats
- Automatic data mapping using existing entity-mapper

Benefits:
- Near real-time updates (<1 minute vs 24 hours)
- Reduced API usage (webhooks vs polling)
- Complements daily incremental sync for redundancy
- Automatic recovery from webhook failures

Files Added:
- lib/types/webhook.ts - TypeScript types and interfaces
- lib/services/webhook-service.ts - Webhook processing service
- app/api/webhooks/autotask/route.ts - Webhook receiver
- app/api/webhooks/logs/route.ts - Logs API
- app/api/webhooks/stats/route.ts - Statistics API
- migrations/004_webhook_support.sql - Database schema
- docs/WEBHOOK_SETUP.md - Complete setup guide (47 sections)
- docs/WEBHOOKS_README.md - Quick start guide

Next Steps:
1. Run database migration
2. Configure webhooks in Autotask
3. Test endpoint and monitor logs

See docs/WEBHOOK_SETUP.md for detailed setup instructions.
 2026-01-24 10:07:20 -05:00
root
8b50cae71c docs: add comprehensive sync behavior documentation 
Created detailed documentation covering:
- Sync types (Full, Incremental, Sync Selected)
- Date range filtering and entity-specific behaviors
- Database operations (UPSERT, soft deletes)
- Foreign key validation mechanisms
- Performance considerations and optimization tips
- Entity-specific filters and requirements
- Troubleshooting guide and best practices
- Workflow examples and API reference

This complements the existing SYNC_INTERFACE_GUIDE.md with
technical implementation details and behavioral specifications.
 2026-01-24 08:43:35 -05:00
root
a14a03140b docs: add comprehensive sync interface user guide 
- Explain all 4 sync options (Full, Incremental, Chunked, Selected)
- Detail when to use each sync type with real-world examples
- Document date range selector and its impact on performance
- List all entities with their dependencies
- Provide best practices for daily, weekly, and monthly syncs
- Include troubleshooting guide for common sync issues
- Add quick reference table for common scenarios
- Explain sync results (added/updated/deleted counts)
- Document API limits and performance considerations
- Reference analysis script for investigating failures

This guide clarifies the sync interface to help users understand what each option does and how to use it effectively.
 2026-01-23 08:32:11 -05:00
root
e25eb3fa5e feat: implement structured logging for sync operations 
- Add comprehensive structured logging utility (lib/utils/sync-logger.ts)
  - Log levels: DEBUG, INFO, WARN, ERROR
  - Automatic error categorization (NETWORK_ERROR, AUTH_ERROR, DATABASE_ERROR, etc.)
  - Phase tracking (INITIALIZING, FETCHING, MAPPING, VALIDATING, UPSERTING, DELETING, COMPLETING)
  - Contextual metadata (syncId, entityType, phase, duration, record counts)
  - Timing helpers for operations

- Update sync-service.ts with structured logging
  - Replace console.log/error with structured logger
  - Consistent error categorization across all error paths
  - Fix swallowed errors in sync history updates
  - Add child loggers for entity-specific operations

- Update entity-sync.ts with structured logging
  - Complete phase tracking throughout sync lifecycle
  - Detailed context for warnings and errors
  - Update chunked sync methods with structured logging
  - Update picklist sync methods (issue types, sub-issue types)
  - Better debugging info with timing and sample data

- Add sync failure analysis script (scripts/analyze-sync-failures.ts)
  - Query sync history by date range, entity type, or status
  - Generate failure summaries by entity
  - Automatic error categorization
  - Calculate success rates and statistics
  - Display detailed sync records with timing

- Add comprehensive documentation (docs/SYNC_LOGGING_IMPROVEMENTS.md)
  - Usage guide and examples
  - Migration guide for developers
  - Before/after comparisons

This addresses inconsistent logging and improves debugging capabilities for sync operations.
 2026-01-23 08:02:02 -05:00
root
df333348f6 Add Datto RMM device API documentation 2025-12-04 23:16:01 -05:00
root
6eee14f8af Add comprehensive admin features and multi-system integration 
- Add admin dashboard with sync controls and data browser
- Implement RMM, Auvik, and Addigy organization mappings
- Add chunked ticket sync with progress tracking
- Implement entity sync service with rate limiting
- Add analytics engine and performance optimizer
- Create data browser for all PSA entities
- Add navigation components and UI improvements
- Implement background processing and sync services
- Add comprehensive documentation and migration scripts
- Update configuration items with multi-system support
- Enhance contact management and purchase history
- Add issue type assignment and LLM analyzer
- Improve error handling and logging utilities
 2025-11-19 14:18:16 -05:00