smart_message 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efdcf78330a702d97c6c59ec11495c04a42ef746fbe6ed12011711ba127a792c
-  data.tar.gz: 395ae151a03376eab42036932e6ebbb437ddd0a42659a8ce8aca64fb80af45e7
+  metadata.gz: 946ebe27d52785f76921ac75921c49e9a9d6532f8714c4aed3b59a6a0eb7b92d
+  data.tar.gz: a40e2fba5460cb900b9ac3fd19689b5a596b069c41c6b17fde7edb7013ef027f
 SHA512:
-  metadata.gz: d307903f836b3f1252bc8e6723c09112c4a89ace6dcb1fbf07581e1782b4ab92899ebaa4d00b74e1c615dd75b7e34a754c2adc84c9c1c894c1e5a679862742a7
-  data.tar.gz: 966a81e21c5348b5c922f068a5edeb5709e73d6ae871eb0c653c76850b7f89ce4d1fde78ff5cd89df03e16cf8558fc6ce40c1949df179ba2f44f977ffe46b718
+  metadata.gz: '06813ab254720233a6136f960ddeb2f9b9e919627c8f4f8ff189a7d9749f0295d42ca8a2366021b7d037fe701db681036705b4b7442e32f1ff054c1e58e2487e'
+  data.tar.gz: 70d76f12b9fa4e0c2c09bfb2482fbd19acee4418fd173be6163de43e703ecc4d3b05329251bab2da5f9760603dafec2178b186ad10f5c779690160245e5f32ce

data/.gitignore

@@ -1,3 +1,4 @@
+/*.log
 /.bundle/
 /.yardoc
 /_yardoc/

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smart_message (0.0.1)
+    smart_message (0.0.2)
       activesupport
       concurrent-ruby
       hashie

data/README.md

@@ -36,10 +36,10 @@ Or install it yourself as:
 
 ```ruby
 class OrderMessage < SmartMessage::Base
-  property :order_id
-  property :customer_id
-  property :amount
-  property :items
+  property :order_id, description: "Unique order identifier"
+  property :customer_id, description: "Customer's unique ID"
+  property :amount, description: "Total order amount in dollars"
+  property :items, description: "Array of ordered items"
 
   # Configure transport and serializer at class level
   config do
@@ -255,9 +255,9 @@ puts dispatcher.subscribers
 
 ```ruby
 class MyMessage < SmartMessage::Base
-  property :user_id
-  property :action
-  property :timestamp, default: -> { Time.now }
+  property :user_id, description: "User's unique identifier"
+  property :action, description: "Action performed by the user"
+  property :timestamp, default: -> { Time.now }, description: "When the action occurred"
 end
 
 message = MyMessage.new(user_id: 123, action: "login")
@@ -266,6 +266,10 @@ message = MyMessage.new(user_id: 123, action: "login")
 puts message.user_id
 puts message.fields  # Returns Set of property names (excluding internal _sm_ properties)
 
+# Access property descriptions
+puts MyMessage.property_description(:user_id)  # => "User's unique identifier"
+puts MyMessage.property_descriptions            # => Hash of all descriptions
+
 # Access message header
 puts message._sm_header.uuid
 puts message._sm_header.message_class

data/docs/README.md

@@ -8,14 +8,15 @@ Welcome to the comprehensive documentation for SmartMessage, a Ruby gem that abs
 - [Installation & Quick Start](getting-started.md)
 - [Basic Usage Examples](examples.md)
 
-### Core Concepts  
+### Core Concepts
 - [Architecture Overview](architecture.md)
 - [Message Lifecycle](message-lifecycle.md)
 - [Plugin System](plugin-system.md)
 
 ### Components
 - [SmartMessage::Base](base.md)
-- [Transport Layer](transports.md) 
+- [Property System](properties.md)
+- [Transport Layer](transports.md)
 - [Serializers](serializers.md)
 - [Dispatcher & Routing](dispatcher.md)
 - [Message Headers](headers.md)
@@ -47,6 +48,6 @@ Welcome to the comprehensive documentation for SmartMessage, a Ruby gem that abs
 
 ## Version
 
-This documentation is for SmartMessage v0.0.1.
+This documentation is for SmartMessage v0.0.2.
 
-For older versions, please check the git tags and corresponding documentation.
+For older versions, please check the git tags and corresponding documentation.

data/docs/properties.md

@@ -0,0 +1,471 @@
+# SmartMessage Property System
+
+The SmartMessage property system builds on Hashie::Dash to provide a robust, declarative way to define message attributes. This document covers all available property options and features.
+
+## Table of Contents
+- [Basic Property Definition](#basic-property-definition)
+- [Class-Level Description](#class-level-description)
+- [Property Options](#property-options)
+- [Accessing Property Information](#accessing-property-information)
+- [Hashie Extensions](#hashie-extensions)
+- [Examples](#examples)
+
+## Basic Property Definition
+
+Properties are defined using the `property` method in your message class:
+
+```ruby
+class MyMessage < SmartMessage::Base
+  property :field_name
+end
+```
+
+## Class-Level Description
+
+In addition to property-level descriptions, you can add a description for the entire message class:
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  description "Handles order processing and fulfillment workflow"
+  
+  property :order_id, description: "Unique order identifier"
+  property :amount, description: "Total amount in cents"
+end
+
+# Access the class description
+OrderMessage.description  # => "Handles order processing and fulfillment workflow"
+
+# Class descriptions can also be set after class definition
+class PaymentMessage < SmartMessage::Base
+  property :payment_id
+end
+
+PaymentMessage.description "Processes payment transactions"
+PaymentMessage.description  # => "Processes payment transactions"
+
+# Can be set within config block
+class NotificationMessage < SmartMessage::Base
+  config do
+    description "Sends notifications to users"
+    transport MyTransport.new
+    serializer MySerializer.new
+  end
+end
+```
+
+Class descriptions are useful for:
+- Documenting the overall purpose of a message class
+- Providing context for code generation tools
+- Integration with documentation systems
+- API documentation generation
+
+Note: Class descriptions are not inherited by subclasses. Each class maintains its own description.
+
+## Property Options
+
+SmartMessage supports all Hashie::Dash property options plus additional features:
+
+### 1. Default Values
+
+Specify a default value for a property when not provided during initialization:
+
+```ruby
+class OrderMessage < SmartMessage::Base
+  # Static default
+  property :status, default: 'pending'
+
+  # Dynamic default using a Proc
+  property :created_at, default: -> { Time.now }
+
+  # Default array
+  property :items, default: []
+end
+
+order = OrderMessage.new
+order.status     # => 'pending'
+order.created_at # => Current time
+order.items      # => []
+```
+
+### 2. Required Properties
+
+Mark properties as required to ensure they're provided during initialization:
+
+```ruby
+class PaymentMessage < SmartMessage::Base
+  property :payment_id, required: true
+  property :amount, required: true
+  property :note  # Optional
+end
+
+# This raises ArgumentError: The property 'payment_id' is required
+PaymentMessage.new(amount: 100)
+
+# This works
+PaymentMessage.new(payment_id: 'PAY-123', amount: 100)
+```
+
+### 3. Property Transformation
+
+Transform property values when they're set:
+
+```ruby
+class UserMessage < SmartMessage::Base
+  property :email, transform_with: ->(v) { v.to_s.downcase }
+  property :name, transform_with: ->(v) { v.to_s.strip.capitalize }
+  property :tags, transform_with: ->(v) { Array(v).map(&:to_s) }
+end
+
+user = UserMessage.new(
+  email: 'USER@EXAMPLE.COM',
+  name: '  john  ',
+  tags: 'admin'
+)
+
+user.email # => 'user@example.com'
+user.name  # => 'John'
+user.tags  # => ['admin']
+```
+
+### 4. Property Translation (from Hashie::Extensions::Dash::PropertyTranslation)
+
+Map external field names to internal property names:
+
+```ruby
+class ApiMessage < SmartMessage::Base
+  property :user_id, from: :userId
+  property :order_date, from: 'orderDate'
+  property :total_amount, from: [:totalAmount, :total, :amount]
+end
+
+# All of these work
+msg1 = ApiMessage.new(userId: 123)
+msg2 = ApiMessage.new(user_id: 123)
+msg3 = ApiMessage.new('orderDate' => '2024-01-01')
+msg4 = ApiMessage.new(totalAmount: 100)  # or total: 100, or amount: 100
+
+msg1.user_id # => 123
+```
+
+### 5. Type Coercion (from Hashie::Extensions::Coercion)
+
+Automatically coerce property values to specific types:
+
+```ruby
+class TypedMessage < SmartMessage::Base
+  property :count
+  property :price
+  property :active
+  property :tags
+  property :metadata
+
+  coerce_key :count, Integer
+  coerce_key :price, Float
+  coerce_key :active, ->(v) { v.to_s.downcase == 'true' }
+  coerce_key :tags, Array[String]
+  coerce_key :metadata, Hash
+end
+
+msg = TypedMessage.new(
+  count: '42',
+  price: '19.99',
+  active: 'yes',
+  tags: 'important',
+  metadata: nil
+)
+
+msg.count    # => 42 (Integer)
+msg.price    # => 19.99 (Float)
+msg.active   # => false (Boolean logic)
+msg.tags     # => ['important'] (Array)
+msg.metadata # => {} (Hash)
+```
+
+### 6. Property Descriptions (SmartMessage Enhancement)
+
+Add human-readable descriptions to document your properties for dynamic LLM integration:
+
+```ruby
+class DocumentedMessage < SmartMessage::Base
+  property :transaction_id,
+           required: true,
+           description: "Unique identifier for the transaction"
+
+  property :amount,
+           transform_with: ->(v) { BigDecimal(v.to_s) },
+           description: "Transaction amount in the smallest currency unit"
+
+  property :currency,
+           default: 'USD',
+           description: "ISO 4217 currency code"
+
+  property :status,
+           default: 'pending',
+           description: "Current transaction status: pending, completed, failed"
+
+  property :metadata,
+           default: {},
+           description: "Additional transaction metadata as key-value pairs"
+end
+
+# Access descriptions programmatically
+DocumentedMessage.property_description(:amount)
+# => "Transaction amount in the smallest currency unit"
+
+DocumentedMessage.property_descriptions
+# => {
+#      transaction_id: "Unique identifier for the transaction",
+#      amount: "Transaction amount in the smallest currency unit",
+#      currency: "ISO 4217 currency code",
+#      status: "Current transaction status: pending, completed, failed",
+#      metadata: "Additional transaction metadata as key-value pairs"
+#    }
+
+DocumentedMessage.described_properties
+# => [:transaction_id, :amount, :currency, :status, :metadata]
+```
+
+## Accessing Property Information
+
+SmartMessage provides several methods to introspect properties:
+
+```ruby
+class IntrospectionExample < SmartMessage::Base
+  property :id, required: true, description: "Unique identifier"
+  property :name, description: "Display name"
+  property :created_at, default: -> { Time.now }
+  property :tags
+end
+
+# Instance methods
+instance = IntrospectionExample.new(id: 1, name: "Test")
+instance.fields  # => Set[:id, :name, :created_at, :tags]
+instance.to_h    # => Hash of all properties and values
+
+# Class methods
+IntrospectionExample.fields              # => Set[:id, :name, :created_at, :tags]
+IntrospectionExample.property_descriptions  # => Hash of descriptions
+IntrospectionExample.described_properties   # => [:id, :name]
+```
+
+## Hashie Extensions
+
+SmartMessage::Base automatically includes these Hashie extensions:
+
+### 1. DeepMerge
+Allows deep merging of nested hash properties:
+
+```ruby
+msg = MyMessage.new(config: { a: 1, b: { c: 2 } })
+msg.deep_merge(config: { b: { d: 3 } })
+# => config: { a: 1, b: { c: 2, d: 3 } }
+```
+
+### 2. IgnoreUndeclared
+Silently ignores properties that haven't been declared:
+
+```ruby
+# Won't raise an error for unknown properties
+msg = MyMessage.new(known: 'value', unknown: 'ignored')
+```
+
+### 3. IndifferentAccess
+Access properties with strings or symbols:
+
+```ruby
+msg = MyMessage.new('name' => 'John')
+msg[:name]    # => 'John'
+msg['name']   # => 'John'
+msg.name      # => 'John'
+```
+
+### 4. MethodAccess
+Access properties as methods:
+
+```ruby
+msg = MyMessage.new(name: 'John')
+msg.name         # => 'John'
+msg.name = 'Jane'
+msg.name         # => 'Jane'
+```
+
+### 5. MergeInitializer
+Allows initializing with merged hash values:
+
+```ruby
+defaults = { status: 'active', retries: 3 }
+msg = MyMessage.new(defaults.merge(status: 'pending'))
+# => status: 'pending', retries: 3
+```
+
+## Examples
+
+### Complete Example: Order Processing Message
+
+```ruby
+class OrderProcessingMessage < SmartMessage::Base
+  description "Manages the complete order lifecycle from placement to delivery"
+  
+  # Required fields with descriptions
+  property :order_id,
+           required: true,
+           description: "Unique order identifier from the ordering system"
+
+  property :customer_id,
+           required: true,
+           description: "Customer who placed the order"
+
+  # Amount with transformation and description
+  property :total_amount,
+           transform_with: ->(v) { BigDecimal(v.to_s) },
+           description: "Total order amount including tax and shipping"
+
+  # Status with default and validation description
+  property :status,
+           default: 'pending',
+           description: "Order status: pending, processing, shipped, delivered, cancelled"
+
+  # Items with coercion
+  property :items,
+           default: [],
+           description: "Array of order line items"
+
+  # Timestamps with dynamic defaults
+  property :created_at,
+           default: -> { Time.now },
+           description: "When the order was created"
+
+  property :updated_at,
+           default: -> { Time.now },
+           description: "Last modification timestamp"
+
+  # Optional fields
+  property :notes,
+           description: "Optional order notes or special instructions"
+
+  property :shipping_address,
+           description: "Shipping address as a nested hash"
+
+  # Field translation for external APIs
+  property :external_ref,
+           from: [:externalReference, :ext_ref],
+           description: "Reference ID from external system"
+end
+
+# Usage
+order = OrderProcessingMessage.new(
+  order_id: 'ORD-2024-001',
+  customer_id: 'CUST-123',
+  total_amount: '149.99',
+  items: [
+    { sku: 'WIDGET-A', quantity: 2, price: 49.99 },
+    { sku: 'WIDGET-B', quantity: 1, price: 50.01 }
+  ],
+  shipping_address: {
+    street: '123 Main St',
+    city: 'Springfield',
+    state: 'IL',
+    zip: '62701'
+  },
+  externalReference: 'EXT-789'  # Note: uses translated field name
+)
+
+# Access properties
+order.order_id         # => 'ORD-2024-001'
+order.total_amount     # => BigDecimal('149.99')
+order.status           # => 'pending' (default)
+order.external_ref     # => 'EXT-789' (translated)
+order.created_at       # => Time object
+
+# Get class and property information
+OrderProcessingMessage.description
+# => "Manages the complete order lifecycle from placement to delivery"
+
+OrderProcessingMessage.property_description(:total_amount)
+# => "Total order amount including tax and shipping"
+
+OrderProcessingMessage.property_descriptions.keys
+# => [:order_id, :customer_id, :total_amount, :status, :items, ...]
+```
+
+### Example: API Integration Message
+
+```ruby
+class ApiWebhookMessage < SmartMessage::Base
+  # Handle different API naming conventions
+  property :event_type,
+           from: [:eventType, :event, :type],
+           required: true,
+           description: "Type of webhook event"
+
+  property :payload,
+           required: true,
+           description: "Event payload data"
+
+  property :timestamp,
+           from: [:timestamp, :created_at, :occurredAt],
+           transform_with: ->(v) { Time.parse(v.to_s) },
+           description: "When the event occurred"
+
+  property :retry_count,
+           from: :retryCount,
+           default: 0,
+           transform_with: ->(v) { v.to_i },
+           description: "Number of delivery attempts"
+
+  property :signature,
+           description: "HMAC signature for webhook validation"
+end
+
+# Can initialize with various field names
+webhook1 = ApiWebhookMessage.new(
+  eventType: 'order.completed',
+  payload: { order_id: 123 },
+  occurredAt: '2024-01-01T10:00:00Z',
+  retryCount: '2'
+)
+
+webhook2 = ApiWebhookMessage.new(
+  type: 'order.completed',        # Alternative field name
+  payload: { order_id: 123 },
+  timestamp: Time.now,             # Alternative field name
+  retry_count: 2                   # Internal field name
+)
+```
+
+## Best Practices
+
+1. **Always add descriptions** to document the purpose and format of each property
+2. **Use required properties** for fields that must be present for valid messages
+3. **Provide sensible defaults** for optional fields to reduce boilerplate
+4. **Use transformations** to ensure data consistency and type safety
+5. **Leverage field translation** when integrating with external APIs that use different naming conventions
+6. **Document valid values** in descriptions for enum-like fields (e.g., status fields)
+7. **Use type coercion** for fields that may come from untrusted sources (like HTTP parameters)
+
+## Property Option Compatibility
+
+Multiple options can be combined on a single property:
+
+```ruby
+property :amount,
+         required: true,
+         from: [:amount, :total, :value],
+         transform_with: ->(v) { BigDecimal(v.to_s) },
+         description: "Transaction amount in cents"
+```
+
+The processing order is:
+1. Field translation (from)
+2. Default value (if not provided)
+3. Required validation
+4. Type coercion
+5. Transformation
+6. Value assignment
+
+## Limitations
+
+- Property names must be valid Ruby method names
+- The `_sm_` prefix is reserved for internal SmartMessage properties
+- Descriptions are metadata only and don't affect runtime behavior
+- Some Hashie options may conflict if used incorrectly (e.g., required with default)

data/lib/smart_message/base.rb

@@ -5,6 +5,7 @@
 require 'securerandom'   # STDLIB
 
 require_relative './wrapper.rb'
+require_relative './property_descriptions.rb'
 
 module SmartMessage
   # The foundation class for the smart message
@@ -18,6 +19,8 @@ module SmartMessage
 
     include Hashie::Extensions::Dash::PropertyTranslation
 
+    include SmartMessage::PropertyDescriptions
+
     include Hashie::Extensions::Coercion
     include Hashie::Extensions::DeepMerge
     include Hashie::Extensions::IgnoreUndeclared
@@ -162,6 +165,17 @@ module SmartMessage
 
     class << self
 
+      #########################################################
+      ## class-level description
+      
+      def description(desc = nil)
+        if desc.nil?
+          @description
+        else
+          @description = desc.to_s
+        end
+      end
+
       #########################################################
       ## class-level configuration
 

data/lib/smart_message/property_descriptions.rb

@@ -0,0 +1,41 @@
+# lib/smart_message/property_descriptions.rb
+# encoding: utf-8
+# frozen_string_literal: true
+
+module SmartMessage
+  module PropertyDescriptions
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval do
+        @property_descriptions = {}
+      end
+    end
+
+    module ClassMethods
+      def property(property_name, options = {})
+        description = options.delete(:description)
+        
+        # Store description if provided
+        if description
+          @property_descriptions ||= {}
+          @property_descriptions[property_name.to_sym] = description
+        end
+        
+        # Call original property method
+        super(property_name, options)
+      end
+
+      def property_description(property_name)
+        @property_descriptions&.[](property_name.to_sym)
+      end
+
+      def property_descriptions
+        @property_descriptions&.dup || {}
+      end
+
+      def described_properties
+        @property_descriptions&.keys || []
+      end
+    end
+  end
+end

data/lib/smart_message/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 module SmartMessage
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smart_message
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -190,6 +190,7 @@ files:
 - docs/examples.md
 - docs/getting-started.md
 - docs/ideas_to_think_about.md
+- docs/properties.md
 - docs/serializers.md
 - docs/transports.md
 - docs/troubleshooting.md
@@ -213,6 +214,7 @@ files:
 - lib/smart_message/header.rb
 - lib/smart_message/logger.rb
 - lib/smart_message/logger/base.rb
+- lib/smart_message/property_descriptions.rb
 - lib/smart_message/serializer.rb
 - lib/smart_message/serializer/base.rb
 - lib/smart_message/serializer/json.rb