nats_wave 1.1.0

data/README.md

@@ -0,0 +1,985 @@
+# 🌊 NatsWave
+
+A comprehensive NATS-based event messaging system for Rails applications that enables seamless communication between
+different teams, products, and services in asset management and valuation workflows.
+
+[![Gem Version](https://badge.fury.io/rb/nats_wave.svg)](https://badge.fury.io/rb/nats_wave)
+[![Build Status](https://github.com/PurpleWave/nats_wave/workflows/CI/badge.svg)](https://github.com/PurpleWave/nats_wave/actions)
+[![Code Climate](https://codeclimate.com/github/PurpleWave/nats_wave/badges/gpa.svg)](https://codeclimate.com/github/PurpleWave/nats_wave)
+[![Test Coverage](https://codeclimate.com/github/PurpleWave/nats_wave/badges/coverage.svg)](https://codeclimate.com/github/PurpleWave/nats_wave/coverage)
+
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Configuration](#-configuration)
+- [Model-Based Architecture](#-model-based-architecture)
+- [Publishing Events](#-publishing-events)
+- [Subscribing to Events](#-subscribing-to-events)
+- [Data Mapping & Transformation](#-data-mapping--transformation)
+- [Monitoring & Metrics](#-monitoring--metrics)
+- [Error Handling](#-error-handling)
+- [Production Deployment](#-production-deployment)
+- [API Reference](#-api-reference)
+- [Examples](#-examples)
+- [Contributing](#-contributing)
+- [License](#-license)
+
+## ✨ Features
+
+- **🚀 Model-Based Configuration** - Configure subscriptions and mappings directly in your models
+- **🔄 Automatic Event Publishing** - ActiveRecord integration publishes model changes automatically
+- **🗺️ Intelligent Data Mapping** - Transform data between different schemas and field names
+- **📊 Datadog Integration** - Built-in metrics and monitoring support
+- **🛡️ Error Handling** - Dead letter queues, retries, and graceful failure handling
+- **🔧 Middleware System** - Authentication, validation, and logging middleware
+- **⚡ High Performance** - Connection pooling, async publishing, and batch operations
+- **🏥 Health Monitoring** - Built-in health checks and status endpoints
+- **📈 Auto-Discovery** - Automatic registration of model subscriptions
+- **🧪 Test-Friendly** - Comprehensive test helpers and mocking support
+
+## 📦 Installation
+
+Add this line to your Rails application's Gemfile:
+
+```ruby
+gem 'nats_wave'
+
+# Optional: For enhanced monitoring
+gem 'dogstatsd-ruby' # For Datadog metrics
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Generate the configuration files:
+
+```bash
+rails generate nats_wave:install
+rails db:migrate
+```
+
+## 🚀 Quick Start
+
+### 1. Basic Configuration
+
+```ruby
+# config/initializers/nats_wave.rb
+NatsWave.configure do |config|
+    config.nats_url = ENV.fetch('NATS_URL', 'nats://localhost:4222')
+    config.service_name = 'valuation_service'
+    config.default_subject_prefix = "#{config.service_name}.events"
+end
+```
+
+### 2. Add to Your Models
+
+```ruby
+# app/models/asset.rb
+class Asset < ApplicationRecord
+    include NatsWave::NatsPublishable
+    include NatsWave::Concerns::Mappable
+    
+    # Automatically publish asset events
+    nats_publishable(
+            actions: [:create, :update, :destroy],
+            skip_attributes: [:notes, :edge_data],
+            include_associations: [:package, :estimates]
+    )
+    
+    # Subscribe to external asset data from IMS
+    nats_wave_maps_from 'IMSAsset',
+                        subjects: ['ims.assets.*', 'inventory.assets.*'],
+                        field_mappings: {
+                                'asset_id' => 'unique_id',
+                                'description' => 'description',
+                                'manufacturer' => 'make',
+                                'model_name' => 'model',
+                                'year_manufactured' => 'year',
+                                'serial_number' => 'serial',
+                                'vin_number' => 'vin'
+                        },
+                        transformations: {
+                                'make' => ->(make) { make&.upcase&.strip },
+                                'year' => ->(year) { year.to_i if year.present? }
+                        },
+                        unique_fields: [:unique_id, :vin, :serial]
+end
+```
+
+### 3. Start the Subscriber
+
+```bash
+# Development - auto-starts with Rails
+rails server
+
+# Production - run dedicated subscriber process
+rails nats_wave:start
+```
+
+### 4. Test the Integration
+
+```bash
+# Test connectivity
+rails nats_wave:health
+
+# Show model subscriptions
+rails nats_wave:model_subscriptions
+
+# Publish a test message
+rails nats_wave:test
+```
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+```bash
+# Required
+NATS_URL=nats://your-nats-server:4222
+SERVICE_NAME=valuation_service
+
+# Optional
+NATS_AUTH_SECRET=your-secret-key
+DD_AGENT_HOST=localhost  # For Datadog metrics
+DD_AGENT_PORT=8125
+```
+
+### Advanced Configuration
+
+```ruby
+# config/initializers/nats_wave.rb
+NatsWave.configure do |config|
+    # NATS Connection
+    config.nats_url = ENV.fetch('NATS_URL')
+    config.service_name = ENV.fetch('SERVICE_NAME')
+    config.connection_pool_size = 10
+    config.reconnect_attempts = 3
+    
+    # Publishing
+    config.publishing_enabled = !Rails.env.test?
+    config.async_publishing = Rails.env.production?
+    config.default_subject_prefix = "#{config.service_name}.events"
+    
+    # Subscription
+    config.subscription_enabled = !Rails.env.test?
+    config.queue_group = "#{config.service_name}_consumers"
+    
+    # Middleware
+    config.middleware_authentication_enabled = Rails.env.production?
+    config.auth_secret_key = ENV['NATS_AUTH_SECRET']
+    config.middleware_logging_enabled = true
+    config.log_level = Rails.env.production? ? 'info' : 'debug'
+    
+    # Error Handling
+    config.max_retries = 3
+    config.retry_delay = 5
+end
+
+# Configure Datadog metrics
+if defined?(Datadog::Statsd)
+    NatsWave::Metrics.configure_datadog(
+            namespace: 'valuation_app.nats_wave',
+            tags: {
+                    service: NatsWave.configuration.service_name,
+                    environment: Rails.env
+            }
+    )
+end
+```
+
+## 🏗️ Model-Based Architecture
+
+NatsWave uses a model-centric approach where each model defines its own subscriptions and mappings.
+
+### Publishing Events
+
+```ruby
+
+class Package < ApplicationRecord
+    include NatsWave::NatsPublishable
+    
+    nats_publishable(
+            actions: [:create, :update], # Which actions to publish
+            skip_attributes: [:notes, :valuation_notes], # Attributes to exclude
+            include_associations: [:organization, :assets, :contact_user], # Include related data
+            if: -> { workflow_status == 'active' }, # Conditional publishing
+            unless: -> { is_shared? }, # Skip conditions
+            subject_prefix: 'packages' # Custom subject prefix
+    )
+    
+    private
+    
+    # Add custom metadata to published events
+    def nats_wave_metadata
+        {
+                organization_name: organization&.name,
+                asset_count: assets.count,
+                total_estimated_value: assets.sum(&:estimated_hammer),
+                valuation_complete: valuation_complete?
+        }
+    end
+end
+```
+
+### Subscribing to External Events
+
+```ruby
+
+class Asset < ApplicationRecord
+    include NatsWave::Concerns::Mappable
+    
+    # Map from inventory management system
+    nats_wave_maps_from 'InventoryAsset',
+                        subjects: ['inventory.assets.*', 'warehouse.assets.*'],
+                        field_mappings: {
+                                'inventory_id' => 'unique_id',
+                                'asset_description' => 'description',
+                                'manufacturer' => 'make',
+                                'model_number' => 'model',
+                                'year_built' => 'year',
+                                'serial_num' => 'serial',
+                                'vin_code' => 'vin',
+                                'location_code' => 'location'
+                        },
+                        transformations: {
+                                'make' => ->(make) { make&.upcase&.strip },
+                                'model' => ->(model) { model&.titleize&.strip },
+                                'year' => ->(year) { year.to_i if year.present? },
+                                'estimated_hammer' => ->(value) { value.to_f.round(2) }
+                        },
+                        unique_fields: [:unique_id, :vin, :serial],
+                        sync_strategy: :upsert,
+                        conditions: {
+                                'status' => 'available',
+                                'condition' => ['good', 'fair', 'excellent']
+                        }
+    
+    # Map from auction system
+    nats_wave_maps_from 'AuctionItem',
+                        subjects: ['auction.items.*'],
+                        field_mappings: {
+                                'lot_number' => 'lot_number',
+                                'hammer_price' => 'pw_contract_price',
+                                'sale_date' => 'pw_contract_date'
+                        },
+                        conditions: {
+                                'auction_status' => 'sold'
+                        }
+end
+```
+
+### Custom Event Handlers
+
+```ruby
+
+class Estimate < ApplicationRecord
+    include NatsWave::Concerns::Mappable
+    
+    # Subscribe to valuation requests
+    nats_wave_subscribes_to 'valuation.requests.*' do |message|
+        ValuationRequestProcessor.process_request(message)
+    end
+    
+    # Subscribe to market price updates
+    nats_wave_subscribes_to 'market.prices.*' do |message|
+        MarketPriceService.update_estimates(message)
+    end
+    
+    # Subscribe to auction results for comparison
+    nats_wave_subscribes_to 'auction.results.*' do |message|
+        AuctionResultAnalyzer.analyze_accuracy(message)
+    end
+end
+```
+
+## 📤 Publishing Events
+
+### Automatic Publishing
+
+Events are automatically published when you include `NatsPublishable` in your models:
+
+```ruby
+# This automatically publishes to "valuation_service.events.asset.create"
+asset = Asset.create!(
+        make: "Caterpillar",
+        model: "320D",
+        year: 2018,
+        serial: "ABC123456",
+        description: "Excavator - Track Type"
+)
+
+# This publishes to "valuation_service.events.asset.update"
+asset.update!(estimated_hammer: 125000)
+
+# This publishes to "valuation_service.events.asset.destroy"
+asset.destroy!
+```
+
+### Manual Publishing
+
+```ruby
+# Publish custom valuation events
+NatsWave.publish(
+        subject: 'valuation.completed',
+        model: 'ValuationSession',
+        action: 'complete',
+        data: {
+                package_id: package.id,
+                asset_count: package.assets.count,
+                total_value: package.total_estimated_value,
+                appraiser_id: current_user.id
+        },
+        metadata: {
+                organization_id: package.organization.id,
+                completion_time: Time.current,
+                valuation_method: 'comparative_analysis'
+        }
+)
+
+# Batch publishing for performance
+events = assets.map do |asset|
+    {
+            subject: 'asset.valued',
+            model: 'Asset',
+            action: 'update',
+            data: asset.attributes.except('notes', 'edge_data')
+    }
+end
+
+NatsWave.client.publish_batch(events)
+```
+
+### Conditional Publishing
+
+```ruby
+
+class Asset < ApplicationRecord
+    include NatsWave::NatsPublishable
+    
+    nats_publishable(
+            if: -> { should_publish_to_external_systems? },
+            unless: -> { asset_status == 'draft' }
+    )
+    
+    private
+    
+    def should_publish_to_external_systems?
+        asset_status == 'completed' &&
+                package.workflow_status == 'finalized' &&
+                !package.is_shared?
+    end
+end
+```
+
+## 📥 Subscribing to Events
+
+### Automatic Model Syncing
+
+When you configure `nats_wave_maps_from`, NatsWave automatically:
+
+1. Subscribes to the specified subjects
+2. Transforms incoming data using field mappings
+3. Applies custom transformations
+4. Syncs data to your local models
+
+```ruby
+# Incoming message from inventory system:
+{
+        "subject": "inventory.assets.update",
+        "model": "InventoryAsset",
+        "action": "update",
+        "data": {
+                "inventory_id": "INV-2024-001",
+                "asset_description": "2020 Ford F-150 Pickup Truck",
+                "manufacturer": "ford",
+                "model_number": "F-150",
+                "year_built": "2020",
+                "serial_num": "1FTFW1ET5LFA12345",
+                "vin_code": "1FTFW1ET5LFA12345",
+                "estimated_value": 35000.00
+        }
+}
+
+# Automatically transforms to:
+{
+        "unique_id": "INV-2024-001",
+        "description": "2020 Ford F-150 Pickup Truck",
+        "make": "FORD",
+        "model": "F-150",
+        "year": 2020,
+        "serial": "1FTFW1ET5LFA12345",
+        "vin": "1FTFW1ET5LFA12345",
+        "estimated_hammer": 35000.00
+}
+
+# And updates/creates the local Asset record
+```
+
+### Custom Subscription Handlers
+
+```ruby
+
+class Organization < ApplicationRecord
+    include NatsWave::Concerns::Mappable
+    
+    # Process user activity for analytics
+    nats_wave_subscribes_to 'users.*.login', 'users.*.logout' do |message|
+        UserActivityTracker.track_activity(message)
+    end
+    
+    # Process package completions with custom queue group
+    nats_wave_subscribes_to 'packages.*.completed',
+                            queue_group: 'reporting_processors' do |message|
+        PackageCompletionReporter.generate_report(message)
+    end
+end
+```
+
+## 🗺️ Data Mapping & Transformation
+
+### Field Mappings
+
+```ruby
+nats_wave_maps_from 'ExternalAsset',
+                    field_mappings: {
+                            'external_id' => 'unique_id',
+                            'asset_make' => 'make',
+                            'asset_model' => 'model',
+                            'manufacture_year' => 'year',
+                            'serial_number' => 'serial',
+                            'vehicle_identification' => 'vin',
+                            'asset_location' => 'location'
+                    }
+```
+
+### Data Transformations
+
+```ruby
+nats_wave_maps_from 'ExternalAsset',
+                    transformations: {
+                            # Lambda transformations
+                            'estimated_hammer' => ->(value) { value.to_f.round(2) },
+                            'make' => ->(make) { make&.upcase&.strip },
+                            'model' => ->(model) { model&.titleize&.strip },
+                            
+                            # Method transformations
+                            'vin' => :normalize_vin,
+                            'serial' => :normalize_serial,
+                            
+                            # Complex transformations with access to full record
+                            'description' => ->(value, record) {
+                                "#{record['year']} #{record['make']} #{record['model']} #{value}".strip
+                            }
+                    }
+
+private
+
+def normalize_vin(vin)
+    vin&.upcase&.gsub(/[^A-Z0-9]/, '')
+end
+
+def normalize_serial(serial)
+    serial&.upcase&.strip
+end
+```
+
+### Conditional Syncing
+
+```ruby
+nats_wave_maps_from 'ExternalAsset',
+                    conditions: {
+                            'status' => 'available', # Exact match
+                            'condition' => ['good', 'fair', 'excellent'], # Array inclusion
+                            'value' => ->(value) { value.to_f > 1000 }, # Custom logic
+                            'category' => /^(vehicle|equipment|machinery)$/ # Regex match
+                    }
+```
+
+### Sync Strategies
+
+```ruby
+nats_wave_maps_from 'ExternalAsset',
+                    sync_strategy: :upsert, # Create or update (default)
+                    # sync_strategy: :create_only, # Only create new records
+                    # sync_strategy: :update_only, # Only update existing records
+                    unique_fields: [:unique_id, :vin, :serial] # Fields to match existing records
+```
+
+## 📊 Monitoring & Metrics
+
+### Datadog Integration
+
+NatsWave provides comprehensive Datadog metrics out of the box:
+
+```ruby
+# Automatic metrics tracked:
+-nats_wave.messages.published # Messages published by subject/model
+-nats_wave.messages.received # Messages received by subject/model  
+-nats_wave.processing_time # Message processing duration
+-nats_wave.errors # Errors by type and subject
+-nats_wave.connection_status # NATS connection health
+-nats_wave.sync.operations # Model sync operations
+-nats_wave.retries # Retry attempts
+-nats_wave.valuations.completed # Valuation completion events
+-nats_wave.assets.synced # Asset synchronization events
+```
+
+### Health Checks
+
+```ruby
+# Built-in health check endpoint
+GET /health/n ats_wave
+
+# Response:
+{
+        "nats_connected": true,
+        "database_connected": true,
+        "timestamp": "2024-01-01T12:00:00Z",
+        "service_name": "valuation_service",
+        "version": "1.1.0",
+        "instance_id": "web-1",
+        "published_subjects": [
+                "valuation_service.events.asset.*",
+                "valuation_service.events.package.*",
+                "valuation_service.events.estimate.*"
+        ],
+        "subscribed_subjects": [
+                "inventory.assets.*",
+                "auction.results.*",
+                "market.prices.*"
+        ],
+        "nats_url": "nats://your-server:4222"
+}
+```
+
+### Monitoring Commands
+
+```bash
+# Check overall health
+rails nats_wave:health
+
+# Show all model subscriptions
+rails nats_wave:model_subscriptions
+
+# Monitor live NATS activity
+rails nats_wave:monitor
+
+# Show failed messages
+rails nats_wave:show_failed
+
+# Retry failed messages
+rails nats_wave:retry_failed
+```
+
+## 🛡️ Error Handling
+
+### Dead Letter Queue
+
+Failed messages are automatically stored in a dead letter queue with retry logic:
+
+```ruby
+# Automatic retry with exponential backoff
+# Retry 1: after 5 seconds
+# Retry 2: after 25 seconds  
+# Retry 3: after 125 seconds
+# After max retries: moved to permanent failure storage
+```
+
+### Error Recovery
+
+```ruby
+# Retry failed messages
+rails nats_wave: retry_failed
+
+# Clear failed messages (after manual review)
+rails nats_wave: clear_failed
+
+# View failed message details
+failed_messages = NatsWave::DeadLetterQueue.new(NatsWave.configuration)
+failed_messages.get_failed_messages.each do |msg|
+    puts "Error: #{msg[:error]}"
+    puts "Retry Count: #{msg[:retry_count]}"
+    puts "Message: #{msg[:message]}"
+end
+```
+
+### Custom Error Handling
+
+```ruby
+
+class CustomErrorHandler
+    def self.handle_failed_message(message, error, retry_count)
+        # Send to monitoring service
+        ErrorTracker.notify(error, {
+                message: message,
+                retry_count: retry_count,
+                service: 'nats_wave'
+        })
+        
+        # Custom retry logic for valuation-specific errors
+        if retry_count < 5 && error.is_a?(ValuationTimeoutError)
+            RetryValuationJob.set(wait: 30.seconds).perform_later(message)
+        end
+    end
+end
+```
+
+## 🚀 Production Deployment
+
+### Docker Setup
+
+```dockerfile
+# Dockerfile
+FROM ruby:3.2-slim
+
+WORKDIR /app
+COPY Gemfile Gemfile.lock ./
+RUN bundle install --deployment
+
+COPY . .
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD curl -f http://localhost:3000/health/nats_wave || exit 1
+
+EXPOSE 3000
+CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"]
+```
+
+### Docker Compose
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  nats:
+    image: nats:latest
+    ports:
+      - "4222:4222"
+      - "8222:8222"
+    command: "--http_port 8222 --js"
+
+  valuation_app:
+    build: .
+    depends_on:
+      - nats
+      - redis
+      - postgres
+    environment:
+      - NATS_URL=nats://nats:4222
+      - SERVICE_NAME=valuation_service
+    ports:
+      - "3000:3000"
+```
+
+### Kubernetes Deployment
+
+```yaml
+# k8s/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: valuation-service
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: valuation-service
+  template:
+    metadata:
+      labels:
+        app: valuation-service
+    spec:
+      containers:
+        - name: app
+          image: valuation-service:latest
+          env:
+            - name: NATS_URL
+              value: "nats://nats-cluster:4222"
+            - name: SERVICE_NAME
+              value: "valuation-service"
+          ports:
+            - containerPort: 3000
+          livenessProbe:
+            httpGet:
+              path: /health/nats_wave
+              port: 3000
+            initialDelaySeconds: 30
+            periodSeconds: 10
+```
+
+### Separate Subscriber Process
+
+For high-volume applications, run subscribers in dedicated processes:
+
+```bash
+# Procfile
+web: bundle exec rails server -p $PORT
+worker: bundle exec rails nats_wave:start
+```
+
+## 💡 Examples
+
+### Asset Management Integration
+
+```ruby
+# app/models/asset.rb
+class Asset < ApplicationRecord
+    include NatsWave::NatsPublishable
+    include NatsWave::Concerns::Mappable
+    
+    nats_publishable(
+            actions: [:create, :update],
+            include_associations: [:package, :estimates, :images]
+    )
+    
+    # Sync from inventory management system
+    nats_wave_maps_from 'InventoryItem',
+                        subjects: ['inventory.items.*'],
+                        field_mappings: {
+                                'item_id' => 'unique_id',
+                                'description' => 'description',
+                                'manufacturer' => 'make',
+                                'model_name' => 'model',
+                                'year_manufactured' => 'year',
+                                'serial_number' => 'serial',
+                                'vin_number' => 'vin',
+                                'location_code' => 'location'
+                        },
+                        transformations: {
+                                'estimated_hammer' => ->(value) { value.to_f.round(2) },
+                                'make' => ->(make) { make&.upcase&.strip }
+                        }
+    
+    # Sync from auction management
+    nats_wave_maps_from 'AuctionAsset',
+                        subjects: ['auction.assets.*'],
+                        field_mappings: {
+                                'lot_number' => 'lot_number',
+                                'hammer_price' => 'pw_contract_price',
+                                'sale_date' => 'pw_contract_date'
+                        },
+                        conditions: {
+                                'status' => 'sold'
+                        }
+end
+
+# app/models/package.rb
+class Package < ApplicationRecord
+    include NatsWave::NatsPublishable
+    
+    nats_publishable(
+            actions: [:create, :update],
+            if: -> { workflow_status == 'finalized' }
+    )
+    
+    # Listen for IMS submission confirmations
+    nats_wave_subscribes_to 'ims.submissions.confirmed.*' do |message|
+        package = Package.find_by(id: message['data']['package_id'])
+        package&.mark_as_submitted!
+    end
+end
+```
+
+### Valuation Workflow
+
+```ruby
+# app/models/estimate.rb
+class Estimate < ApplicationRecord
+    include NatsWave::NatsPublishable
+    include NatsWave::Concerns::Mappable
+    
+    nats_publishable(
+            skip_attributes: [:notes, :source_data]
+    )
+    
+    # Sync from external valuation service
+    nats_wave_maps_from 'ExternalValuation',
+                        subjects: ['valuations.external.*'],
+                        field_mappings: {
+                                'valuation_id' => 'key',
+                                'asset_identifier' => 'asset_id',
+                                'appraiser_id' => 'user_id',
+                                'estimated_value' => 'value',
+                                'valuation_notes' => 'notes'
+                        },
+                        transformations: {
+                                'value' => ->(value) { (value.to_f * 100).round }, # Convert to cents
+                                'notes' => ->(notes) { notes&.strip }
+                        },
+                        unique_fields: [:key, :asset_id, :user_id]
+    
+    # Listen for market price updates
+    nats_wave_subscribes_to 'market.prices.*' do |message|
+        MarketPriceAnalyzer.update_estimates_based_on_market(message)
+    end
+end
+
+# app/models/valuation_request.rb
+class ValuationRequest < ApplicationRecord
+    include NatsWave::NatsPublishable
+    
+    nats_publishable(
+            actions: [:create, :update]
+    )
+    
+    # Process valuation assignments
+    nats_wave_subscribes_to 'valuations.assignments.*' do |message|
+        ValuationAssignmentProcessor.process_assignment(message)
+    end
+end
+```
+
+### Organization & User Management
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+    include NatsWave::NatsPublishable
+    include NatsWave::Concerns::Mappable
+    
+    nats_publishable(
+            skip_attributes: [:api_auth_key, :source_details]
+    )
+    
+    # Sync from authentication service
+    nats_wave_maps_from 'AuthUser',
+                        subjects: ['auth.users.*'],
+                        field_mappings: {
+                                'user_id' => 'key',
+                                'email_address' => 'email',
+                                'full_name' => 'name',
+                                'is_active' => 'active'
+                        },
+                        transformations: {
+                                'email' => ->(email) { email&.downcase },
+                                'active' => ->(active) { active == 'true' || active == true }
+                        },
+                        unique_fields: [:key, :email]
+end
+
+# app/models/organization.rb
+class Organization < ApplicationRecord
+    include NatsWave::NatsPublishable
+    include NatsWave::Concerns::Mappable
+    
+    nats_publishable(
+            skip_attributes: [:api_auth_key, :workflow_config]
+    )
+    
+    # Sync from CRM system
+    nats_wave_maps_from 'CRMOrganization',
+                        subjects: ['crm.organizations.*'],
+                        field_mappings: {
+                                'organization_id' => 'key',
+                                'company_name' => 'name',
+                                'primary_contact' => 'contact',
+                                'email_address' => 'email',
+                                'phone_number' => 'phone',
+                                'is_active' => 'active'
+                        },
+                        unique_fields: [:key, :name]
+end
+```
+
+### Image and Media Processing
+
+```ruby
+# app/models/image.rb
+class Image < ApplicationRecord
+    include NatsWave::NatsPublishable
+    
+    nats_publishable(
+            actions: [:create, :update],
+            skip_attributes: [:source_data, :import_url],
+            if: -> { !deleted? && sizes.present? }
+    )
+    
+    # Listen for image processing completion
+    nats_wave_subscribes_to 'media.processing.completed.*' do |message|
+        ImageProcessingService.handle_completion(message)
+    end
+    
+    # Listen for IMS image submissions
+    nats_wave_subscribes_to 'ims.images.*' do |message|
+        IMSImageProcessor.process_submission(message)
+    end
+end
+
+# app/models/video.rb
+class Video < ApplicationRecord
+    include NatsWave::NatsPublishable
+    
+    nats_publishable(
+            actions: [:create, :update],
+            if: -> { !deleted? && url.present? }
+    )
+    
+    # Listen for video processing updates
+    nats_wave_subscribes_to 'media.videos.*' do |message|
+        VideoProcessingService.handle_update(message)
+    end
+end
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CODE_OF_CONDUCT.md) for details.
+
+### Development Setup
+
+```bash
+git clone https://github.com/PurpleWave/nats_wave.git
+cd nats_wave
+bundle install
+
+# Start NATS server for testing
+docker run -p 4222:4222 -p 8222:8222 nats:latest --http_port 8222
+
+# Run tests
+bundle exec rspec
+
+# Run linting
+bundle exec rubocop
+```
+
+### Testing
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test files
+bundle exec rspec spec/nats_wave/publisher_spec.rb
+
+# Run with coverage
+COVERAGE=true bundle exec rspec
+```
+
+## 📝 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for details about changes in each version.
+
+## 📄 License
+
+This gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## 🙋‍♂️ Support
+
+- **Documentation**: [GitHub Wiki](https://github.com/PurpleWave/nats_wave/wiki)
+- **Issues**: [GitHub Issues](https://github.com/PurpleWave/nats_wave/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/PurpleWave/nats_wave/discussions)
+
+## 🏢 About Purple Wave
+
+NatsWave is developed and maintained by [Purple Wave](https://purplewave.com) to enable seamless communication between
+our microservices and teams in the asset valuation and auction industry.
+
+---
+
+**Made with ❤️ by Jeffrey Dabo**