shoko 0.1.0

data/lib/shoko/core/events/annotation_events.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative 'base_domain_event'
+
+module Shoko
+  module Core
+    module Events
+      # Domain event for annotation creation
+      class AnnotationAdded < BaseDomainEvent
+        required_attributes :book_path, :annotation
+        typed_attributes book_path: String
+
+        def initialize(book_path:, annotation:, **)
+          super(
+            aggregate_id: book_path,
+            book_path: book_path,
+            annotation: annotation,
+            **
+          )
+        end
+
+        def book_path
+          get_attribute(:book_path)
+        end
+
+        def annotation
+          get_attribute(:annotation)
+        end
+      end
+
+      # Domain event for annotation updates
+      class AnnotationUpdated < BaseDomainEvent
+        required_attributes :book_path, :annotation_id, :old_note, :new_note
+        typed_attributes book_path: String, annotation_id: String, old_note: String,
+                         new_note: String
+
+        def initialize(book_path:, annotation_id:, old_note:, new_note:, **)
+          super(
+            aggregate_id: book_path,
+            book_path: book_path,
+            annotation_id: annotation_id,
+            old_note: old_note,
+            new_note: new_note,
+            **
+          )
+        end
+
+        def book_path
+          get_attribute(:book_path)
+        end
+
+        def annotation_id
+          get_attribute(:annotation_id)
+        end
+
+        def old_note
+          get_attribute(:old_note)
+        end
+
+        def new_note
+          get_attribute(:new_note)
+        end
+      end
+
+      # Domain event for annotation removal
+      class AnnotationRemoved < BaseDomainEvent
+        required_attributes :book_path, :annotation_id
+        typed_attributes book_path: String, annotation_id: String
+
+        def initialize(book_path:, annotation_id:, annotation: nil, **)
+          super(
+            aggregate_id: book_path,
+            book_path: book_path,
+            annotation_id: annotation_id,
+            annotation: annotation,
+            **
+          )
+        end
+
+        def book_path
+          get_attribute(:book_path)
+        end
+
+        def annotation_id
+          get_attribute(:annotation_id)
+        end
+
+        def annotation
+          get_attribute(:annotation)
+        end
+      end
+    end
+  end
+end

data/lib/shoko/core/events/base_domain_event.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module Shoko
+  module Core
+    module Events
+      # Base class for all domain events.
+      #
+      # Domain events represent something that has happened in the domain
+      # and are used to trigger side effects and maintain loose coupling
+      # between different parts of the system.
+      #
+      # @example Creating a domain event
+      #   class BookmarkAdded < BaseDomainEvent
+      #     attribute :book_path, String
+      #     attribute :bookmark, Bookmark
+      #   end
+      #
+      # @example Using a domain event
+      #   event = BookmarkAdded.new(book_path: '/path/to/book.epub', bookmark: bookmark)
+      #   event_bus.publish(event)
+      class BaseDomainEvent
+        # Event metadata
+        attr_reader :event_id, :occurred_at, :aggregate_id, :version
+
+        def initialize(aggregate_id: nil, version: 1, **attributes)
+          @event_id = SecureRandom.uuid
+          @occurred_at = Time.now.utc
+          @aggregate_id = aggregate_id
+          @version = version
+          @attributes = attributes
+
+          validate_required_attributes
+          validate_attribute_types
+        end
+
+        # Get event type name
+        #
+        # @return [String] Event type name
+        def event_type
+          self.class.name.split('::').last
+        end
+
+        # Get event data as hash
+        #
+        # @return [Hash] Event data
+        def event_data
+          @attributes.dup
+        end
+
+        # Get specific attribute value
+        #
+        # @param name [Symbol] Attribute name
+        # @return [Object] Attribute value
+        def get_attribute(name)
+          @attributes[name]
+        end
+
+        # Convert event to hash for serialization
+        #
+        # @return [Hash] Serialized event
+        def to_h
+          {
+            event_id: @event_id,
+            event_type: event_type,
+            occurred_at: @occurred_at.iso8601,
+            aggregate_id: @aggregate_id,
+            version: @version,
+            data: @attributes,
+          }
+        end
+
+        # Create event from hash
+        #
+        # @param hash [Hash] Serialized event data
+        # @return [BaseDomainEvent] Reconstructed event
+        def self.from_h(hash)
+          event = allocate
+          event.instance_variable_set(:@event_id, hash[:event_id] || hash['event_id'])
+          event.instance_variable_set(:@occurred_at,
+                                      Time.parse(hash[:occurred_at] || hash['occurred_at']))
+          event.instance_variable_set(:@aggregate_id, hash[:aggregate_id] || hash['aggregate_id'])
+          event.instance_variable_set(:@version, hash[:version] || hash['version'] || 1)
+          event.instance_variable_set(:@attributes, hash[:data] || hash['data'] || {})
+          event
+        end
+
+        # Define required attributes for the event
+        #
+        # @example
+        #   class MyEvent < BaseDomainEvent
+        #     required_attributes :user_id, :action
+        #   end
+        def self.required_attributes(*attrs)
+          @required_attributes ||= []
+          @required_attributes.concat(attrs) if attrs.any?
+          @required_attributes
+        end
+
+        # Define typed attributes for the event
+        #
+        # @example
+        #   class MyEvent < BaseDomainEvent
+        #     typed_attributes user_id: String, count: Integer
+        #   end
+        def self.typed_attributes(types = {})
+          @typed_attributes ||= {}
+          @typed_attributes.merge!(types) if types.any?
+          @typed_attributes
+        end
+
+        # Check if event is of specific type
+        #
+        # @param type [String, Symbol] Event type to check
+        # @return [Boolean] True if event is of specified type
+        def of_type?(type)
+          event_type == type.to_s
+        end
+
+        # String representation of the event
+        #
+        # @return [String] String representation
+        def to_s
+          "#{event_type}(#{@event_id})[#{@occurred_at}]"
+        end
+
+        # Equality comparison
+        #
+        # @param other [BaseDomainEvent] Other event to compare
+        # @return [Boolean] True if events are equal
+        def ==(other)
+          return false unless other.is_a?(BaseDomainEvent)
+
+          @event_id == other.event_id &&
+            event_type == other.event_type &&
+            @attributes == other.event_data
+        end
+
+        private
+
+        def validate_required_attributes
+          klass = self.class
+          required = klass.required_attributes
+          return unless required
+
+          missing = required - @attributes.keys
+          return if missing.empty?
+
+          raise ArgumentError, "Missing required attributes: #{missing.join(', ')}"
+        end
+
+        def validate_attribute_types
+          klass = self.class
+          typed = klass.typed_attributes
+          return unless typed
+
+          typed.each do |attr, type|
+            value = @attributes[attr]
+            next if value.nil? # Allow nil values
+
+            raise TypeError, "Attribute #{attr} must be of type #{type}, got #{value.class}" unless value.is_a?(type)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/core/events/bookmark_events.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'base_domain_event'
+
+module Shoko
+  module Core
+    module Events
+      # Common base for bookmark-related events
+      class BookmarkEventBase < BaseDomainEvent
+        required_attributes :book_path, :bookmark
+        typed_attributes book_path: String
+
+        def initialize(book_path:, bookmark:, **)
+          super(
+            aggregate_id: book_path,
+            book_path: book_path,
+            bookmark: bookmark,
+            **
+          )
+        end
+
+        def book_path
+          get_attribute(:book_path)
+        end
+
+        def bookmark
+          get_attribute(:bookmark)
+        end
+      end
+
+      # Domain event for bookmark creation
+      class BookmarkAdded < BookmarkEventBase; end
+
+      # Domain event for bookmark removal
+      class BookmarkRemoved < BookmarkEventBase; end
+
+      # Domain event for bookmark navigation
+      class BookmarkNavigated < BookmarkEventBase; end
+    end
+  end
+end

data/lib/shoko/core/events/domain_event_bus.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative 'base_domain_event.rb'
+
+module Shoko
+  module Core
+    module Events
+      # Domain event bus for publishing and subscribing to domain events.
+      #
+      # This provides a domain-specific event bus that sits on top of the
+      # infrastructure event bus and handles domain event serialization,
+      # routing, and subscription management.
+      #
+      # @example Publishing an event
+      #   event_bus.publish(BookmarkAdded.new(book_path: path, bookmark: bookmark))
+      #
+      # @example Subscribing to events
+      #   event_bus.subscribe(BookmarkAdded) { |event| handle_bookmark_added(event) }
+      class DomainEventBus
+        def initialize(infrastructure_event_bus)
+          @infrastructure_bus = infrastructure_event_bus
+          @subscribers = Hash.new { |h, k| h[k] = [] }
+          @middleware = []
+        end
+
+        # Publish a domain event
+        #
+        # @param event [Core::Events::BaseDomainEvent] Domain event to publish
+        def publish(event)
+          unless event.is_a?(Core::Events::BaseDomainEvent)
+            raise ArgumentError, 'Event must be a BaseDomainEvent'
+          end
+
+          # Apply middleware chain
+          processed_event = apply_middleware(event)
+          return if processed_event.nil? # Event was filtered out
+
+          # Publish through infrastructure bus
+          @infrastructure_bus.emit_event(
+            processed_event.event_type.to_sym,
+            event_data: processed_event.to_h
+          )
+
+          # Notify domain subscribers directly
+          notify_subscribers(processed_event)
+        end
+
+        # Subscribe to a specific event type
+        #
+        # @param event_type [Class] Event class to subscribe to
+        # @param handler [Proc] Handler block or callable
+        # @yield [event] Block to handle the event
+        def subscribe(event_type, handler = nil, &)
+          handler = resolve_callable!(handler, &)
+          @subscribers[event_type] << handler
+        end
+
+        # Subscribe to multiple event types with the same handler
+        #
+        # @param event_types [Array<Class>] Event classes to subscribe to
+        # @param handler [Proc] Handler block or callable
+        # @yield [event] Block to handle the event
+        def subscribe_to_many(event_types, handler = nil, &)
+          handler = resolve_callable!(handler, &)
+          event_types.each { |type| subscribe(type, handler) }
+        end
+
+        # Unsubscribe from an event type
+        #
+        # @param event_type [Class] Event class to unsubscribe from
+        # @param handler [Proc] Specific handler to remove (optional)
+        def unsubscribe(event_type, handler = nil)
+          if handler
+            @subscribers[event_type].delete(handler)
+          else
+            @subscribers.delete(event_type)
+          end
+        end
+
+        # Add middleware to the event processing pipeline
+        #
+        # @param middleware [Proc] Middleware that processes events
+        # @yield [event] Block that processes the event and returns modified event or nil
+        def add_middleware(middleware = nil, &block)
+          middleware = block if block_given?
+          raise ArgumentError, 'Middleware must be provided' unless middleware
+
+          @middleware << middleware
+        end
+
+        def resolve_callable!(callable, &block)
+          callable = block if block_given?
+          raise ArgumentError, 'Handler must be provided' unless callable
+
+          callable
+        end
+
+        # Get all subscribers for an event type
+        #
+        # @param event_type [Class] Event class
+        # @return [Array<Proc>] List of subscribers
+        def subscribers_for(event_type)
+          @subscribers[event_type].dup
+        end
+
+        # Check if there are subscribers for an event type
+        #
+        # @param event_type [Class] Event class
+        # @return [Boolean] True if there are subscribers
+        def subscribers?(event_type)
+          @subscribers[event_type].any?
+        end
+
+        # Clear all subscribers (useful for testing)
+        def clear_subscribers
+          @subscribers.clear
+        end
+
+        # Get subscriber count for an event type
+        #
+        # @param event_type [Class] Event class
+        # @return [Integer] Number of subscribers
+        def subscriber_count(event_type)
+          @subscribers[event_type].size
+        end
+
+        # Get total number of subscribers across all event types
+        #
+        # @return [Integer] Total subscriber count
+        def total_subscribers
+          @subscribers.values.sum(&:size)
+        end
+
+        private
+
+        def apply_middleware(event)
+          @middleware.reduce(event) do |current_event, middleware|
+            next current_event if current_event.nil?
+
+            begin
+              middleware.call(current_event)
+            rescue StandardError => e
+              # Log middleware error but don't stop event processing
+              warn "Domain event middleware error: #{e.message}"
+              current_event
+            end
+          end
+        end
+
+        def notify_subscribers(event)
+          event_type = event.class
+
+          @subscribers[event_type].each do |handler|
+            handler.call(event)
+          rescue StandardError => e
+            # Log subscriber error but continue with other subscribers
+            warn "Domain event subscriber error for #{event_type}: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/core/events/progress_events.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative 'base_domain_event'
+
+module Shoko
+  module Core
+    module Events
+      # Domain event for reading progress updates
+      class ProgressUpdated < BaseDomainEvent
+        required_attributes :book_path, :chapter_index, :line_offset
+        typed_attributes book_path: String, chapter_index: Integer, line_offset: Integer
+
+        def initialize(book_path:, chapter_index:, line_offset:, previous_chapter: nil,
+                       previous_line: nil, **)
+          super(
+            aggregate_id: book_path,
+            book_path: book_path,
+            chapter_index: chapter_index,
+            line_offset: line_offset,
+            previous_chapter: previous_chapter,
+            previous_line: previous_line,
+            **
+          )
+        end
+
+        def book_path
+          get_attribute(:book_path)
+        end
+
+        def chapter_index
+          get_attribute(:chapter_index)
+        end
+
+        def line_offset
+          get_attribute(:line_offset)
+        end
+
+        def previous_chapter
+          get_attribute(:previous_chapter)
+        end
+
+        def previous_line
+          get_attribute(:previous_line)
+        end
+
+        # Check if this represents forward progress
+        def forward_progress?
+          return true if previous_chapter.nil? || previous_line.nil?
+
+          chapter_index > previous_chapter ||
+            (chapter_index == previous_chapter && line_offset > previous_line)
+        end
+      end
+
+      # Domain event for reading session start
+      class ReadingSessionStarted < BaseDomainEvent
+        required_attributes :book_path
+        typed_attributes book_path: String
+
+        def initialize(book_path:, **)
+          super(
+            aggregate_id: book_path,
+            book_path: book_path,
+            **
+          )
+        end
+
+        def book_path
+          get_attribute(:book_path)
+        end
+      end
+
+      # Domain event for reading session end
+      class ReadingSessionEnded < BaseDomainEvent
+        required_attributes :book_path, :duration_seconds
+        typed_attributes book_path: String, duration_seconds: Integer
+
+        def initialize(book_path:, duration_seconds:, final_chapter: nil, final_line: nil,
+                       **)
+          super(
+            aggregate_id: book_path,
+            book_path: book_path,
+            duration_seconds: duration_seconds,
+            final_chapter: final_chapter,
+            final_line: final_line,
+            **
+          )
+        end
+
+        def book_path
+          get_attribute(:book_path)
+        end
+
+        def duration_seconds
+          get_attribute(:duration_seconds)
+        end
+
+        def final_chapter
+          get_attribute(:final_chapter)
+        end
+
+        def final_line
+          get_attribute(:final_line)
+        end
+      end
+    end
+  end
+end

data/lib/shoko/core/models/bookmark.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Shoko
+  module Core
+    module Models
+      # Represents a bookmark within a document.
+      Bookmark = Struct.new(:chapter_index, :line_offset, :text_snippet, :created_at,
+                            keyword_init: true) do
+        # Build from hash loaded from disk
+        # @param hash [Hash]
+        # @return [Bookmark]
+        def self.from_h(hash)
+          new(
+            chapter_index: hash['chapter'],
+            line_offset: hash['line_offset'],
+            text_snippet: hash['text'],
+            created_at: Time.parse(hash['timestamp'])
+          )
+        end
+
+        # Convert to hash for persistence
+        # @return [Hash]
+        def to_h
+          {
+            'chapter' => chapter_index,
+            'line_offset' => line_offset,
+            'text' => text_snippet,
+            'timestamp' => created_at.iso8601,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/shoko/core/models/bookmark_data.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Core
+    module Models
+      # Data object for adding bookmarks
+      BookmarkData = Struct.new(:path, :chapter, :line_offset, :text, keyword_init: true)
+    end
+  end
+end

data/lib/shoko/core/models/chapter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Core
+    module Models
+      # Represents a chapter within an EPUB document.
+      Chapter = Struct.new(:number, :title, :lines, :metadata, :blocks, :raw_content,
+                           keyword_init: true) do
+        # Number of lines in the chapter
+        # @return [Integer]
+        def line_count
+          lines.size
+        end
+
+        # Estimated reading time in minutes
+        # @param wpm [Integer] words per minute
+        # @return [Integer]
+        def estimated_reading_time(wpm = 250)
+          word_count = lines.join(' ').split.size
+          (word_count / wpm.to_f).ceil
+        end
+      end
+    end
+  end
+end

data/lib/shoko/core/models/content_block.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Core
+    module Models
+      # Represents a unit of formatted content (heading, paragraph, list item, etc.).
+      ContentBlock = Struct.new(:type, :segments, :level, :metadata, keyword_init: true) do
+        def text
+          segments.to_a.map { |segment| segment&.text.to_s }.join
+        end
+
+        def heading_level
+          (metadata && metadata[:level]) || level
+        end
+      end
+
+      # Represents a contiguous run of text with associated inline styles.
+      TextSegment = Struct.new(:text, :styles, keyword_init: true) do
+        def initialize(text:, styles: nil)
+          super(text: text.to_s, styles: (styles || {}).freeze)
+        end
+
+        def length
+          text.to_s.length
+        end
+      end
+
+      # Represents a display-ready line produced by the formatting pipeline.
+      DisplayLine = Struct.new(:text, :segments, :metadata, keyword_init: true) do
+        def initialize(text:, segments:, metadata: nil)
+          super(text: text.to_s, segments: segments || [], metadata: metadata || {})
+        end
+
+        def length
+          text.length
+        end
+
+        def empty?
+          text.strip.empty?
+        end
+      end
+    end
+  end
+end