ee_e_business_register 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 19fcfcfebdc8ee468082d775697e5ad1813cadf6165bf7fe6b6c77a75a9f4d13
+  data.tar.gz: 3da6375585851f412fe18216fda7aae2d925cd198a9b12c4a02bc0bf2d5f5a72
+SHA512:
+  metadata.gz: 0b548ee045fa8bb892abc34a68bd0e4f1919a7573fe7fc6b1f32831008751dddaec2c8e4ddece612a77c2edb00e00727f9e58c72186d86b654eecdc8704220f8
+  data.tar.gz: 72207a5f26c7445a26a9716242142200ecb7a3f7da76c41c08de3b5daccdf3d697bd1fb86c4da184ee3721c66eb36e3dd73e62427ed9a90c4e1547f6734357aa

data/.ee_business_register_credentials.yml.example

@@ -0,0 +1,8 @@
+# Estonian e-Business Register API Credentials
+# 
+# Copy this file to ~/.ee_business_register_credentials.yml and fill in your credentials
+# You can obtain credentials by signing an agreement with the Registers and Information Systems Center
+# Visit: https://www.rik.ee/en/e-business-register/open-data-api
+#
+username: your_username_here
+password: your_password_here

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Enhanced documentation with comprehensive examples and walkthroughs
+- Professional polish for production-ready release
+- Improved demo application navigation and UX
+- Additional gemspec metadata for better RubyGems integration
+
+### Changed
+- Polished all code comments and documentation strings for clarity
+- Reviewed and improved all example code in documentation
+- Enhanced error messages for better user experience
+
+## [0.2.0] - 2024-12-XX
+
+### Added
+- Beneficial owners endpoint support (`get_beneficial_owners`)
+- Comprehensive model classes for all data types
+- Enhanced error handling with specific exception types
+- Complete demo application with all endpoints
+- Professional UI/UX for demo application
+- Extensive documentation with real-world examples
+
+### Changed
+- Updated API operation mappings to current Estonian API version
+- Improved data parsing and model conversion
+- Enhanced client retry logic and timeout handling
+- Deprecated company name search functionality (API limitation)
+
+### Deprecated
+- `search_companies` method - Estonian API removed name search capability
+- `find_companies_like` method - functionality no longer available
+
+### Fixed
+- Registry code validation and normalization
+- Date parsing and type conversion issues
+- SOAP response parsing edge cases
+- Model initialization with nil values
+- Demo application navigation and routing
+
+### Security
+- Input sanitization for all user-provided data
+- Prevention of XML/SOAP injection attacks
+- Validation of Estonian registry codes and personal codes
+
+## [0.1.0] - 2025-08-27
+
+### Added
+- Initial release of the Estonian e-Business Register API client
+- Basic company lookup functionality
+- SOAP client with authentication
+- Core data models (Company, Address)
+- Configuration system
+- Basic error handling
+- Unit tests and integration tests
+- Demo application framework
+
+### Features
+- Find companies by registry code
+- Get company details and documents
+- Access annual reports
+- Retrieve classifiers and reference data
+- Health check endpoint
+- Type-safe data models with dry-struct
+- Bilingual support (Estonian/English)
+
+---
+
+## Contributing
+
+When making changes, please:
+
+1. Add entries to the `[Unreleased]` section
+2. Use the following categories: Added, Changed, Deprecated, Removed, Fixed, Security
+3. Follow the format: `- Description of change (#PR-number)`
+4. Move entries to a new version section when releasing
+
+## Release Process
+
+1. Update the version number in `lib/ee_e_business_register/version.rb`
+2. Move unreleased changes to a new version section in this changelog
+3. Update the date for the new version
+4. Create a git tag with the version number
+5. Build and publish the gem to RubyGems
+
+For more details, see the [Contributing Guidelines](CONTRIBUTING.md).

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Angelos Kapsimanis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Makefile

@@ -0,0 +1,392 @@
+# Estonian e-Business Register Ruby Gem Makefile
+# Professional FinTech-grade automation for development workflow
+#
+# This Makefile provides a complete development and deployment workflow for the
+# Estonian e-Business Register Ruby gem, including testing with API rate limiting,
+# version management, building, and publishing to RubyGems.
+#
+# Key features:
+# - API throttling for Estonian registry (1-second delays)
+# - Comprehensive testing suite (unit + integration)
+# - Automated version management with semantic versioning
+# - Safe publishing workflow with confirmations
+# - Code quality enforcement with RuboCop
+# - Git integration for tagging and releases
+#
+# Usage:
+#   make help         - Show available commands
+#   make test         - Run all tests with API throttling
+#   make build        - Build the gem package
+#   make demo         - Build gem and launch Sinatra demo app
+#   make version-up   - Increment version number
+#   make publish      - Publish to RubyGems.org
+#   make release      - Complete release workflow
+
+# Ensure all targets are treated as commands, not files
+# This prevents make from looking for files with these names
+.PHONY: help test test-unit test-integration build clean install version-up publish lint format demo
+
+# Terminal color codes for professional output formatting
+# These make the output more readable and user-friendly
+GREEN = \033[0;32m    # Success messages
+YELLOW = \033[0;33m   # Warning messages  
+RED = \033[0;31m      # Error messages
+BLUE = \033[0;34m     # Info messages
+NC = \033[0m          # No Color (reset)
+
+# Configuration variables for the gem
+# These can be easily modified if the gem structure changes
+GEM_NAME = ee_e_business_register
+VERSION_FILE = lib/ee_e_business_register/version.rb
+
+#==============================================================================
+# HELP AND DOCUMENTATION
+#==============================================================================
+
+# Default target - shows help when user runs 'make' without arguments
+# This provides a user-friendly entry point to discover available commands
+help: ## Show this help message
+	@echo "$(BLUE)Estonian e-Business Register Gem$(NC)"
+	@echo "$(BLUE)=================================$(NC)"
+	@echo ""
+	@echo "Available commands:"
+	# Extract all targets with ## comments and format them nicely
+	# This automatically generates help from the inline documentation
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  $(GREEN)%-15s$(NC) %s\n", $$1, $$2}'
+	@echo ""
+	@echo "$(YELLOW)Note: API tests include 1-second delays due to rate limiting$(NC)"
+
+#==============================================================================
+# TESTING COMMANDS
+#==============================================================================
+
+# Main test command - runs all tests with proper API throttling
+# The Estonian e-Business Register API has rate limits, so we add delays
+# between test files to avoid hitting the limits and getting blocked
+# Tests include: basic company lookup, detailed company data (detailandmed_v2),
+# classifiers, error handling, and comprehensive data model validation
+test: ## Run all tests with API rate limiting delays
+	@echo "$(GREEN)Running complete test suite with API throttling...$(NC)"
+	# Custom test runner that loads each test file individually with delays
+	# This ensures we don't overwhelm the Estonian API with rapid requests
+	@bundle exec ruby -Ilib:test -e '\
+		require "minitest/autorun"; \
+		Dir.glob("test/**/test_*.rb").each do |file|; \
+			puts "Loading: #{file}"; \
+			require_relative file; \
+			sleep 1; \
+		end'
+	@echo "$(GREEN)✓ All tests completed including detailed company and documents functionality$(NC)"
+	@echo "$(BLUE)Detailed company data tests validate:$(NC)"
+	@echo "  • General company information (addresses, activities, contacts)"
+	@echo "  • Personnel data (board members, shareholders with OSAN/O roles)"
+	@echo "  • Comprehensive business activity codes (EMTAK/NACE)"
+	@echo "  • Estonian address system integration (ADS)"
+	@echo "$(BLUE)Company documents tests validate:$(NC)"
+	@echo "  • Annual reports (PDF, XBRL, DDOC/BDOC formats)"
+	@echo "  • Articles of association documents"
+	@echo "  • Document filtering by type, year, and validity"
+	@echo "  • Document metadata (size, URLs, status dates)"
+	@echo "$(YELLOW)Note: API integration tests require real credentials$(NC)"
+	@echo "$(YELLOW)Create ~/.ee_business_register_credentials.yml with username and password$(NC)"
+
+# Unit tests only - these don't make API calls so no throttling needed
+# Useful for quick feedback during development without hitting API limits
+test-unit: ## Run unit tests only (no API calls)
+	@echo "$(GREEN)Running unit tests (excluding integration tests)...$(NC)"
+	# Exclude integration tests to avoid any API calls
+	# This gives developers fast feedback on code changes
+	@bundle exec ruby -Ilib:test -e '\
+		require "minitest/autorun"; \
+		Dir.glob("test/**/test_*.rb").reject { |f| f.include?("integration") }.each do |file|; \
+			puts "Loading: #{file}"; \
+			require_relative file; \
+		end'
+
+# Integration tests with real API calls - requires valid credentials
+# These tests actually connect to the Estonian e-Business Register
+# and verify that our gem works with the real API
+test-integration: ## Run integration tests with real API (requires credentials)
+	@echo "$(GREEN)Running integration tests with 1-second API throttling...$(NC)"
+	# Check if credentials file exists before attempting API tests
+	# This prevents confusing error messages for new developers
+	@if [ ! -f ~/.ee_business_register_credentials.yml ]; then \
+		echo "$(RED)Error: Credentials file not found at ~/.ee_business_register_credentials.yml$(NC)"; \
+		echo "$(YELLOW)Please create credentials file or skip integration tests$(NC)"; \
+		exit 1; \
+	fi
+	# Run only the integration test file with API throttling
+	@bundle exec ruby -Ilib:test test/integration_test.rb
+	@sleep 1  # Additional delay after integration tests
+
+#==============================================================================
+# BUILD AND PACKAGING
+#==============================================================================
+
+# Build the gem package from the gemspec
+# This creates a .gem file that can be installed or published
+build: clean ## Build the gem package
+	@echo "$(GREEN)Building $(GEM_NAME) gem...$(NC)"
+	# Use bundler's gem build command for consistency
+	# This ensures all dependencies and configurations are respected
+	@bundle exec gem build $(GEM_NAME).gemspec
+	@echo "$(GREEN)✓ Gem built successfully$(NC)"
+	# Show the built gem file(s) for verification
+	@ls -la *.gem 2>/dev/null || echo "$(RED)No gem file found$(NC)"
+
+# Clean up build artifacts to ensure fresh builds
+# Important for avoiding conflicts between different versions
+clean: ## Clean built artifacts
+	@echo "$(GREEN)Cleaning build artifacts...$(NC)"
+	# Remove gem files and packaging directories
+	@rm -f *.gem
+	@rm -rf pkg/
+	@echo "$(GREEN)✓ Clean complete$(NC)"
+
+# Install the gem locally for testing
+# Useful for testing the gem in local Ruby environment
+install: build ## Install the gem locally
+	@echo "$(GREEN)Installing $(GEM_NAME) locally...$(NC)"
+	# Install the most recently built gem file
+	@gem install *.gem
+	@echo "$(GREEN)✓ Gem installed locally$(NC)"
+
+#==============================================================================
+# VERSION MANAGEMENT
+#==============================================================================
+
+# Display current version from the version file
+# Useful for checking version before releases
+version: ## Show current version
+	@echo "$(GREEN)Current version:$(NC)"
+	# Extract version string from VERSION constant in Ruby file
+	@grep VERSION $(VERSION_FILE) | cut -d'"' -f2
+
+# Increment patch version (x.y.z -> x.y.z+1)
+# Use this for bug fixes and minor updates
+version-up: ## Increment patch version (x.y.z -> x.y.z+1)
+	@echo "$(GREEN)Incrementing patch version...$(NC)"
+	# Use Ruby to safely modify the version file
+	# This handles the version format correctly and atomically
+	@ruby -i -pe '\
+		if /VERSION = "(\d+)\.(\d+)\.(\d+)"/ then \
+			gsub(/VERSION = "(\d+)\.(\d+)\.(\d+)"/, "VERSION = \"#{$$1}.#{$$2}.#{$$3.to_i + 1}\"") \
+		end' $(VERSION_FILE)
+	@echo "$(GREEN)✓ Version updated to:$(NC) $$(make version)"
+	@echo "$(YELLOW)Don't forget to commit the version change!$(NC)"
+
+# Increment minor version (x.y.z -> x.y+1.0)
+# Use this for new features that are backward compatible
+version-up-minor: ## Increment minor version (x.y.z -> x.y+1.0)
+	@echo "$(GREEN)Incrementing minor version...$(NC)"
+	# Reset patch version to 0 when incrementing minor
+	@ruby -i -pe '\
+		if /VERSION = "(\d+)\.(\d+)\.(\d+)"/ then \
+			gsub(/VERSION = "(\d+)\.(\d+)\.(\d+)"/, "VERSION = \"#{$$1}.#{$$2.to_i + 1}.0\"") \
+		end' $(VERSION_FILE)
+	@echo "$(GREEN)✓ Version updated to:$(NC) $$(make version)"
+	@echo "$(YELLOW)Don't forget to commit the version change!$(NC)"
+
+# Increment major version (x.y.z -> x+1.0.0)  
+# Use this for breaking changes or major new features
+version-up-major: ## Increment major version (x.y.z -> x+1.0.0)
+	@echo "$(GREEN)Incrementing major version...$(NC)"
+	# Reset minor and patch versions to 0 when incrementing major
+	@ruby -i -pe '\
+		if /VERSION = "(\d+)\.(\d+)\.(\d+)"/ then \
+			gsub(/VERSION = "(\d+)\.(\d+)\.(\d+)"/, "VERSION = \"#{$$1.to_i + 1}.0.0\"") \
+		end' $(VERSION_FILE)
+	@echo "$(GREEN)✓ Version updated to:$(NC) $$(make version)"
+	@echo "$(YELLOW)Don't forget to commit the version change!$(NC)"
+
+#==============================================================================
+# PUBLISHING TO RUBYGEMS
+#==============================================================================
+
+# Publish gem to RubyGems.org - this is irreversible!
+# Includes safety confirmation to prevent accidental publishing
+publish: build ## Publish gem to RubyGems.org
+	@echo "$(GREEN)Publishing $(GEM_NAME) to RubyGems.org...$(NC)"
+	@echo "$(YELLOW)Current version: $$(make version)$(NC)"
+	@echo "$(YELLOW)Are you sure you want to publish? This cannot be undone.$(NC)"
+	# Interactive confirmation to prevent accidental publishing
+	# Publishing to RubyGems is permanent and cannot be reverted
+	@read -p "Type 'yes' to confirm: " confirm; \
+	if [ "$$confirm" = "yes" ]; then \
+		gem push *.gem && \
+		echo "$(GREEN)✓ Gem published successfully!$(NC)" && \
+		echo "$(BLUE)View at: https://rubygems.org/gems/$(GEM_NAME)$(NC)"; \
+	else \
+		echo "$(YELLOW)Publish cancelled$(NC)"; \
+	fi
+
+# Dry run for publishing - test the process without actually publishing
+# Useful for validating that everything is ready for publication
+publish-dry-run: build ## Simulate publishing (safe test)
+	@echo "$(GREEN)Dry run: simulating gem publish...$(NC)"
+	@echo "$(YELLOW)Version: $$(make version)$(NC)"
+	@echo "$(YELLOW)Gem file: $$(ls *.gem)$(NC)"
+	@echo "$(GREEN)✓ Ready to publish (use 'make publish' to actually publish)$(NC)"
+
+#==============================================================================
+# CODE QUALITY AND LINTING
+#==============================================================================
+
+# Run RuboCop static code analysis
+# Ensures code follows Ruby community standards
+lint: ## Run RuboCop linter
+	@echo "$(GREEN)Running RuboCop linter...$(NC)"
+	# Check both lib and test directories for style issues
+	# Simple format provides clean, readable output
+	@bundle exec rubocop lib/ test/ --format simple
+	@echo "$(GREEN)✓ Linting complete$(NC)"
+
+# Auto-fix RuboCop violations where possible
+# Saves developer time by automatically fixing simple style issues
+lint-fix: ## Run RuboCop with auto-correct
+	@echo "$(GREEN)Running RuboCop with auto-correct...$(NC)"
+	# Automatically fix issues that can be safely corrected
+	@bundle exec rubocop lib/ test/ --auto-correct
+	@echo "$(GREEN)✓ Auto-corrections applied$(NC)"
+
+# Alias for lint-fix for convenience
+format: lint-fix ## Alias for lint-fix
+
+#==============================================================================
+# DEVELOPMENT HELPERS
+#==============================================================================
+
+# Install all gem dependencies
+# Essential setup step for new development environments
+deps: ## Install dependencies
+	@echo "$(GREEN)Installing dependencies...$(NC)"
+	# Use bundler to install all dependencies from Gemfile
+	@bundle install
+	@echo "$(GREEN)✓ Dependencies installed$(NC)"
+
+# Update all dependencies to latest compatible versions
+# Important for security updates and bug fixes
+deps-update: ## Update dependencies
+	@echo "$(GREEN)Updating dependencies...$(NC)"
+	# Update all gems to latest versions within constraints
+	@bundle update
+	@echo "$(GREEN)✓ Dependencies updated$(NC)"
+
+# Start interactive console with gem pre-loaded
+# Useful for testing gem functionality interactively
+console: ## Start interactive console with gem loaded
+	@echo "$(GREEN)Starting interactive console...$(NC)"
+	# Use the provided console script which loads the gem
+	@bundle exec bin/console
+
+# Launch the Sinatra demo application
+# Builds the gem first to ensure latest version is used in demo
+demo: build ## Build gem and launch Sinatra demo app
+	@echo "$(GREEN)Building gem and launching Sinatra demo application...$(NC)"
+	@echo "$(BLUE)Starting Estonian e-Business Register API Demo$(NC)"
+	@echo "$(BLUE)============================================$(NC)"
+	# Install the freshly built gem locally for demo to use latest version
+	@echo "$(YELLOW)Installing latest gem version for demo...$(NC)"
+	@gem install *.gem --local --force > /dev/null 2>&1 || true
+	# Navigate to demo directory and start the Sinatra app
+	@echo "$(GREEN)Starting demo app at http://localhost:4567$(NC)"
+	@echo "$(YELLOW)Press Ctrl+C to stop the server$(NC)"
+	@echo ""
+	# Change to demo directory and run the startup script
+	@cd ../demo_app && ruby start.rb
+
+#==============================================================================
+# GIT INTEGRATION
+#==============================================================================
+
+# Create git tag for current version
+# Important for tracking releases and enabling rollbacks
+git-tag: ## Create git tag for current version
+	@echo "$(GREEN)Creating git tag for version $$(make version)...$(NC)"
+	# Create annotated tag with version message
+	# Annotated tags include metadata like date and author
+	@git tag -a "v$$(make version)" -m "Release version $$(make version)"
+	@echo "$(GREEN)✓ Tag created: v$$(make version)$(NC)"
+	@echo "$(YELLOW)Push with: git push origin v$$(make version)$(NC)"
+
+# Push all tags to remote repository
+# Makes tags available to other developers and CI/CD systems
+git-push-tags: ## Push all tags to origin
+	@echo "$(GREEN)Pushing tags to origin...$(NC)"
+	# Push all local tags to the remote repository
+	@git push origin --tags
+	@echo "$(GREEN)✓ Tags pushed$(NC)"
+
+#==============================================================================
+# COMPLETE RELEASE WORKFLOW
+#==============================================================================
+
+# Complete automated release process
+# Combines all release steps into a single command for convenience
+release: version-up build test git-tag publish git-push-tags ## Complete release workflow
+	@echo "$(GREEN)🎉 Release complete!$(NC)"
+	@echo "$(BLUE)Version $$(make version) has been:$(NC)"
+	@echo "  • Built and tested"
+	@echo "  • Tagged in git"  
+	@echo "  • Published to RubyGems"
+	@echo "  • Tags pushed to origin"
+
+#==============================================================================
+# STATUS AND DIAGNOSTICS
+#==============================================================================
+
+# Show comprehensive project status
+# Useful for debugging and understanding current state
+status: ## Show project status
+	@echo "$(BLUE)Estonian e-Business Register Gem Status$(NC)"
+	@echo "$(BLUE)=======================================$(NC)"
+	# Display current version
+	@echo "Version: $$(make version)"
+	# Count built gem files
+	@echo "Gem files: $$(ls *.gem 2>/dev/null | wc -l | tr -d ' ') built"
+	# Show git status if this is a git repository
+	@echo "Git status:"
+	@git status --porcelain || echo "  (not a git repository)"
+	@echo ""
+	# Check if dependencies are satisfied
+	@echo "Dependencies:"
+	@bundle check >/dev/null 2>&1 && echo "  ✓ All dependencies satisfied" || echo "  ⚠ Run 'make deps' to install dependencies"
+	@echo ""
+	# Check for API credentials
+	@echo "Credentials:"
+	@[ -f ~/.ee_business_register_credentials.yml ] && echo "  ✓ API credentials configured" || echo "  ⚠ No credentials file found"
+
+#==============================================================================
+# SECURITY AND PERFORMANCE
+#==============================================================================
+
+# Run security audit on all dependencies
+# Important for FinTech applications to identify vulnerabilities
+security-audit: ## Run security audit on dependencies
+	@echo "$(GREEN)Running security audit...$(NC)"
+	# Use bundler-audit to check for known vulnerabilities
+	# Update the vulnerability database first
+	@bundle audit check --update
+	@echo "$(GREEN)✓ Security audit complete$(NC)"
+
+# Generate documentation (placeholder for future implementation)
+# Professional gems should include comprehensive documentation
+docs: ## Generate documentation (placeholder)
+	@echo "$(GREEN)Generating documentation...$(NC)"
+	@echo "$(YELLOW)Documentation generation not yet implemented$(NC)"
+	@echo "$(BLUE)See README.md for current documentation$(NC)"
+
+# Run basic performance benchmarks
+# Helps identify performance regressions during development
+benchmark: ## Run basic performance benchmarks
+	@echo "$(GREEN)Running performance benchmarks...$(NC)"
+	# Simple benchmark of basic operations
+	# Note: This will make real API calls if credentials are configured
+	@bundle exec ruby -Ilib -e '\
+		require "ee_e_business_register"; \
+		require "benchmark"; \
+		puts "Note: Benchmarks will make real API calls if credentials are configured"; \
+		puts "Basic configuration benchmark:"; \
+		Benchmark.bm do |x|; \
+			x.report("Config creation:") { 1000.times { EeEBusinessRegister::Configuration.new } }; \
+		end'