ox-tender-abstract 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83274157e46a8de668555603f4627528bbd27d091cf682157e24d5b47474fa98
+  data.tar.gz: 6f4465d33a0b748e02803495259fa30d66c23c5cc9a2f8de0ec7ff56cb2787b7
+SHA512:
+  metadata.gz: 628bc14dadbd989cae0eef11bb608c05219e2432f59b9342b3dcfae22172db6e6dafcba6caf163477fb5e5792a659454243d02c413d2127dfafb0e11941b3923
+  data.tar.gz: 70ecc6574d26ce57653540c420684718beaca51e485ab2c9c788a1575d07f1a8c6de0df2a2dcccf05287372c7b4d2f3cc3b8428a340e4f8b7c77f3a94a19823b

data/.cursor/rules/010-project-structure.mdc

@@ -0,0 +1,11 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Overview
+
+## Code Conventions
+
+- Use `snake_case` for method and variable names
+- All code comments, CHANGELOG, README, and other documentation must be written in English

data/.cursor/rules/998-clean-code.mdc

@@ -0,0 +1,62 @@
+---
+description: Guidelines for writing clean, maintainable, and human-readable code. Apply these rules when writing or reviewing code to ensure consistency and quality.
+globs: 
+alwaysApply: false
+---
+
+# Clean Code Guidelines
+
+## Constants Over Magic Numbers
+
+- Replace hard-coded values with named constants
+- Use descriptive constant names that explain the value's purpose
+- Keep constants at the top of the file or in a dedicated constants file
+
+## Meaningful Names
+
+- Variables, functions, and classes should reveal their purpose
+- Names should explain why something exists and how it's used
+- Avoid abbreviations unless they're universally understood
+
+## Smart Comments
+
+- Don't comment on what the code does - make the code self-documenting
+- Use comments to explain why something is done a certain way
+- Document APIs, complex algorithms, and non-obvious side effects
+
+## Single Responsibility
+
+- Each function should do exactly one thing
+- Functions should be small and focused
+- If a function needs a comment to explain what it does, it should be split
+
+## DRY (Don't Repeat Yourself)
+
+- Extract repeated code into reusable functions
+- Share common logic through proper abstraction
+- Maintain single sources of truth
+
+## Clean Structure
+
+- Keep related code together
+- Organize code in a logical hierarchy
+- Use consistent file and folder naming conventions
+
+## Encapsulation
+
+- Hide implementation details
+- Expose clear interfaces
+- Move nested conditionals into well-named functions
+
+## Code Quality Maintenance
+
+- Refactor continuously
+- Fix technical debt early
+- Leave code cleaner than you found it
+- Follow the "Fail fast" principle for early error detection
+
+## Version Control
+
+- Write clear commit messages
+- Make small, focused commits
+- Use meaningful branch names

data/.cursor/rules/999-mdc-format.mdc

@@ -0,0 +1,132 @@
+---
+description: 
+globs: *.mdc,**/*.mdc
+alwaysApply: false
+---
+# MDC File Format Guide
+
+MDC (Markdown Configuration) files are used by Cursor to provide context-specific instructions to AI assistants. This guide explains how to create and maintain these files properly.
+
+## File Structure
+
+Each MDC file consists of two main parts:
+
+1. **Frontmatter** - Configuration metadata at the top of the file
+2. **Markdown Content** - The actual instructions in Markdown format
+
+### Frontmatter
+
+The frontmatter must be the first thing in the file and must be enclosed between triple-dash lines (`---`). Configuration should be based on the intended behavior:
+
+```
+---
+# Configure your rule based on desired behavior:
+
+description: Brief description of what the rule does
+globs: **/*.js, **/*.ts  # Optional: Comma-separated list, not an array
+alwaysApply: false       # Set to true for global rules
+---
+```
+
+> **Important**: Despite the appearance, the frontmatter is not strictly YAML formatted. The `globs` field is a comma-separated list and should NOT include brackets `[]` or quotes `"`.
+
+#### Guidelines for Setting Fields
+
+- **description**: Should be agent-friendly and clearly describe when the rule is relevant. Format as `<topic>: <details>` for best results.
+- **globs**:
+  - If a rule is only relevant in very specific situations, leave globs empty so it's loaded only when applicable to the user request.
+  - If the only glob would match all files (like `**/*`), leave it empty and set `alwaysApply: true` instead.
+  - Otherwise, be as specific as possible with glob patterns to ensure rules are only applied with relevant files.
+- **alwaysApply**: Use sparingly for truly global guidelines.
+
+#### Glob Pattern Examples
+
+- **/*.js - All JavaScript files
+- src/**/*.jsx - All JSX files in the src directory
+- **/components/**/*.vue - All Vue files in any components directory
+
+### Markdown Content
+
+After the frontmatter, the rest of the file should be valid Markdown:
+
+```markdown
+# Title of Your Rule
+
+## Section 1
+- Guidelines and information
+- Code examples
+
+## Section 2
+More detailed information...
+```
+
+## Special Features
+
+### File References
+
+You can reference other files from within an MDC file using the markdown link syntax:
+
+```
+[rule-name.mdc](mdc:location/of/the/rule.mdc)
+```
+
+When this rule is activated, the referenced file will also be included in the context.
+
+### Code Blocks
+
+Use fenced code blocks for examples:
+
+````markdown
+```javascript
+// Example code
+function example() {
+  return "This is an example";
+}
+```
+````
+
+## Best Practices
+
+1. **Clear Organization**
+   - Use numbered prefixes (e.g., `01-workflow.mdc`) for sorting rules logically
+   - Place task-specific rules in the `tasks/` subdirectory
+   - Use descriptive filenames that indicate the rule's purpose
+
+2. **Frontmatter Specificity**
+   - Be specific with glob patterns to ensure rules are only applied in relevant contexts
+   - Use `alwaysApply: true` for truly global guidelines
+   - Make descriptions clear and concise so AI knows when to apply the rule
+
+3. **Content Structure**
+   - Start with a clear title (H1)
+   - Use hierarchical headings (H2, H3, etc.) to organize content
+   - Include examples where appropriate
+   - Keep instructions clear and actionable
+
+4. **File Size Considerations**
+   - Keep files focused on a single topic or closely related topics
+   - Split very large rule sets into multiple files and link them with references
+   - Aim for under 300 lines per file when possible
+
+## Usage in Cursor
+
+When working with files in Cursor, rules are automatically applied when:
+
+1. The file you're working on matches a rule's glob pattern
+2. A rule has `alwaysApply: true` set in its frontmatter
+3. The agent thinks the rule's description matches the user request
+4. You explicitly reference a rule in a conversation with Cursor's AI
+
+## Creating/Renaming/Removing Rules
+
+- When a rule file is added/renamed/removed, update also the list under 010-workflow.mdc.
+- When changs are made to multiple `mdc` files from a single request, review also [999-mdc-format]((mdc:.cursor/rules/999-mdc-format.mdc)) to consider whether to update it too.
+
+## Updating Rules
+
+When updating existing rules:
+
+1. Maintain the frontmatter format
+2. Keep the same glob patterns unless intentionally changing the rule's scope
+3. Update the description if the purpose of the rule changes
+4. Consider whether changes should propagate to related rules (e.g., CE versions)

data/.cursor/rules/api-integration.mdc

@@ -0,0 +1,63 @@
+# Zakupki.gov.ru API Integration Guide
+
+## SOAP API Workflow
+
+1. **Authentication**: Use `individualPerson_token` header
+2. **Request**: Call `get_docs_by_org_region` or `get_docs_by_reestr_number`
+3. **Response**: Receive archive URLs in SOAP response
+4. **Download**: Fetch archives (GZIP compressed ZIP files)
+5. **Extract**: Decompress GZIP → Extract ZIP → Parse XML files
+
+## Key API Methods
+
+- `get_docs_by_org_region` - Search by region and date
+- `get_docs_by_reestr_number` - Search by registry number
+
+## Document Types ([document_types.rb](mdc:lib/oxtenderabstract/document_types.rb))
+
+- **PRIZ**: Procurement procedures (default)
+- **RPEC**: Registry of procurement participants  
+- **RCON**: Registry of contracts
+- **Other**: Various subsystem types
+
+## XML Structure Handling
+
+- Use multiple XPath expressions for reliability
+- Handle namespaces properly with `extract_namespaces`
+- Support both namespaced (ns5:) and non-namespaced elements
+- Extract dates, prices, and text with specific helper methods
+
+## Archive Processing
+
+- Support GZIP and ZIP formats
+- Limit file sizes (100MB max)
+- Handle network errors gracefully
+- Extract all XML files from archives
+
+## Error Handling Patterns
+
+```ruby
+# Network errors
+rescue SocketError, Timeout::Error => e
+  Result.failure("Network error: #{e.message}")
+
+# SOAP errors  
+rescue Savon::SOAPFault => e
+  Result.failure("SOAP Fault: #{e.message}")
+
+# Archive errors
+rescue Zip::Error => e
+  raise ArchiveError, "ZIP extraction error: #{e.message}"
+```
+
+## Configuration Requirements
+
+- API token is required for authentication
+- Configurable timeouts for network operations
+- SSL verification can be disabled for testing
+- Logger for debugging API interactions
+description:
+globs:
+alwaysApply: false
+
+---

data/.cursor/rules/project-structure.mdc

@@ -0,0 +1,113 @@
+---
+alwaysApply: true
+---
+
+# OxTenderAbstract Project Structure
+
+This is a Ruby gem for working with Russian tender system (zakupki.gov.ru) SOAP API.
+
+## Main Entry Point
+
+The main entry point is [lib/ox-tender-abstract.rb](mdc:lib/ox-tender-abstract.rb), which loads all modules and provides convenience methods.
+
+## Core Architecture
+
+### Main Library Modules (lib/oxtenderabstract/)
+
+- [client.rb](mdc:lib/oxtenderabstract/client.rb) - Main SOAP API client with search and download methods
+- [xml_parser.rb](mdc:lib/oxtenderabstract/xml_parser.rb) - XML document parser for tender data extraction
+- [archive_processor.rb](mdc:lib/oxtenderabstract/archive_processor.rb) - Archive download and extraction (GZIP/ZIP)
+- [result.rb](mdc:lib/oxtenderabstract/result.rb) - Result wrapper for success/failure responses
+- [configuration.rb](mdc:lib/oxtenderabstract/configuration.rb) - Library configuration and global settings
+- [errors.rb](mdc:lib/oxtenderabstract/errors.rb) - Custom error classes hierarchy
+- [document_types.rb](mdc:lib/oxtenderabstract/document_types.rb) - Constants for API document types
+- [logger.rb](mdc:lib/oxtenderabstract/logger.rb) - Contextual logging module
+- [version.rb](mdc:lib/oxtenderabstract/version.rb) - Gem version definition
+
+### Tests Structure (spec/)
+
+- [spec/spec_helper.rb](mdc:spec/spec_helper.rb) - RSpec configuration and setup
+- [spec/oxtenderabstract_spec.rb](mdc:spec/oxtenderabstract_spec.rb) - Main module tests
+- [spec/oxtenderabstract/](mdc:spec/oxtenderabstract/) - Individual module tests
+
+### Configuration Files
+
+- [ox-tender-abstract.gemspec](mdc:ox-tender-abstract.gemspec) - Gem specification and dependencies
+- [Gemfile](mdc:Gemfile) - Development dependencies
+- [README.md](mdc:README.md) - Project documentation
+
+## Data Flow
+
+1. **API Request**: Client → SOAP API → Archive URLs
+2. **Archive Processing**: ArchiveProcessor → Download → Extract (GZIP→ZIP→XML)
+3. **XML Parsing**: XmlParser → Structured tender data
+4. **Result**: Result wrapper with success/failure status
+
+## Key Dependencies
+
+- `savon` - SOAP client
+- `nokogiri` - XML parsing
+- `rubyzip` - ZIP archive handling
+- `net-http` - HTTP client
+
+## Usage Pattern
+
+```ruby
+OxTenderAbstract.configure { |config| config.token = 'token' }
+result = OxTenderAbstract.search_tenders(org_region: '77', exact_date: '2024-01-01')
+```
+
+# OxTenderAbstract Project Structure
+
+This is a Ruby gem for working with Russian tender system (zakupki.gov.ru) SOAP API.
+
+## Main Entry Point
+
+The main entry point is [lib/ox-tender-abstract.rb](mdc:lib/ox-tender-abstract.rb), which loads all modules and provides convenience methods.
+
+## Core Architecture
+
+### Main Library Modules (lib/oxtenderabstract/)
+
+- [client.rb](mdc:lib/oxtenderabstract/client.rb) - Main SOAP API client with search and download methods
+- [xml_parser.rb](mdc:lib/oxtenderabstract/xml_parser.rb) - XML document parser for tender data extraction
+- [archive_processor.rb](mdc:lib/oxtenderabstract/archive_processor.rb) - Archive download and extraction (GZIP/ZIP)
+- [result.rb](mdc:lib/oxtenderabstract/result.rb) - Result wrapper for success/failure responses
+- [configuration.rb](mdc:lib/oxtenderabstract/configuration.rb) - Library configuration and global settings
+- [errors.rb](mdc:lib/oxtenderabstract/errors.rb) - Custom error classes hierarchy
+- [document_types.rb](mdc:lib/oxtenderabstract/document_types.rb) - Constants for API document types
+- [logger.rb](mdc:lib/oxtenderabstract/logger.rb) - Contextual logging module
+- [version.rb](mdc:lib/oxtenderabstract/version.rb) - Gem version definition
+
+### Tests Structure (spec/)
+
+- [spec/spec_helper.rb](mdc:spec/spec_helper.rb) - RSpec configuration and setup
+- [spec/oxtenderabstract_spec.rb](mdc:spec/oxtenderabstract_spec.rb) - Main module tests
+- [spec/oxtenderabstract/](mdc:spec/oxtenderabstract/) - Individual module tests
+
+### Configuration Files
+
+- [ox-tender-abstract.gemspec](mdc:ox-tender-abstract.gemspec) - Gem specification and dependencies
+- [Gemfile](mdc:Gemfile) - Development dependencies
+- [README.md](mdc:README.md) - Project documentation
+
+## Data Flow
+
+1. **API Request**: Client → SOAP API → Archive URLs
+2. **Archive Processing**: ArchiveProcessor → Download → Extract (GZIP→ZIP→XML)
+3. **XML Parsing**: XmlParser → Structured tender data
+4. **Result**: Result wrapper with success/failure status
+
+## Key Dependencies
+
+- `savon` - SOAP client
+- `nokogiri` - XML parsing
+- `rubyzip` - ZIP archive handling
+- `net-http` - HTTP client
+
+## Usage Pattern
+
+```ruby
+OxTenderAbstract.configure { |config| config.token = 'token' }
+result = OxTenderAbstract.search_tenders(org_region: '77', exact_date: '2024-01-01')
+```

data/.cursor/rules/ruby-conventions.mdc

@@ -0,0 +1,121 @@
+---
+alwaysApply: true
+---
+
+# Ruby Coding Conventions
+
+## Naming Conventions
+
+- Use `snake_case` for method and variable names
+- Use `PascalCase` for class and module names
+- Use `SCREAMING_SNAKE_CASE` for constants
+
+## Documentation
+
+- All code comments, CHANGELOG, README, and other documentation must be written in English
+- Use YARD-style documentation for public methods
+- Include examples in documentation when appropriate
+
+## Code Organization
+
+- Each class should be in its own file
+- Follow the single responsibility principle
+- Use modules for shared functionality (like ContextualLogger)
+
+## Error Handling
+
+- Use custom error classes that inherit from the base Error class
+- Return Result objects for operations that can fail
+- Handle exceptions gracefully and provide meaningful error messages
+
+## Method Structure
+
+- Public methods should be well-documented
+- Private methods should be clearly marked with `private`
+- Use descriptive method names that explain what they do
+
+## Testing
+
+- Use RSpec for testing
+- Test both success and failure cases
+- Use descriptive test names that explain the expected behavior
+- Mock external dependencies appropriately
+
+## Dependencies
+
+- Prefer standard library when possible
+- Use well-maintained gems for complex functionality
+- Keep dependencies minimal and justified
+
+## Result Pattern
+
+Use the Result pattern for operations that can fail:
+
+```ruby
+def some_operation
+  # success case
+  Result.success(data)
+rescue => e
+  # failure case  
+  Result.failure(e.message)
+end
+```
+
+# Ruby Coding Conventions
+
+## Naming Conventions
+
+- Use `snake_case` for method and variable names
+- Use `PascalCase` for class and module names
+- Use `SCREAMING_SNAKE_CASE` for constants
+
+## Documentation
+
+- All code comments, CHANGELOG, README, and other documentation must be written in English
+- Use YARD-style documentation for public methods
+- Include examples in documentation when appropriate
+
+## Code Organization
+
+- Each class should be in its own file
+- Follow the single responsibility principle
+- Use modules for shared functionality (like ContextualLogger)
+
+## Error Handling
+
+- Use custom error classes that inherit from the base Error class
+- Return Result objects for operations that can fail
+- Handle exceptions gracefully and provide meaningful error messages
+
+## Method Structure
+
+- Public methods should be well-documented
+- Private methods should be clearly marked with `private`
+- Use descriptive method names that explain what they do
+
+## Testing
+
+- Use RSpec for testing
+- Test both success and failure cases
+- Use descriptive test names that explain the expected behavior
+- Mock external dependencies appropriately
+
+## Dependencies
+
+- Prefer standard library when possible
+- Use well-maintained gems for complex functionality
+- Keep dependencies minimal and justified
+
+## Result Pattern
+
+Use the Result pattern for operations that can fail:
+
+```ruby
+def some_operation
+  # success case
+  Result.success(data)
+rescue => e
+  # failure case  
+  Result.failure(e.message)
+end
+```

data/.cursor/rules/testing-patterns.mdc

@@ -0,0 +1,169 @@
+---
+alwaysApply: true
+---
+
+# Testing Patterns
+
+## RSpec Configuration
+
+- Use [spec/spec_helper.rb](mdc:spec/spec_helper.rb) for global test setup
+- Configure RSpec with `--require spec_helper` in [.rspec](mdc:.rspec)
+- Load path includes `lib/` directory for proper module loading
+
+## Test Structure
+
+- One test file per main class: `spec/oxtenderabstract/class_name_spec.rb`
+- Group related tests with `describe` and `context` blocks
+- Use descriptive test names that explain expected behavior
+
+## Mocking Patterns
+
+```ruby
+# Mock external dependencies
+let(:mock_response) { instance_double(Net::HTTPResponse) }
+allow(mock_response).to receive(:is_a?).with(Net::HTTPSuccess).and_return(true)
+allow(mock_response).to receive(:body).and_return('content')
+allow(mock_response).to receive(:[]).with('content-type').and_return('application/zip')
+
+# Mock internal classes
+let(:client_double) { instance_double(OxTenderAbstract::Client) }
+allow(OxTenderAbstract::Client).to receive(:new).and_return(client_double)
+```
+
+## Configuration Reset
+
+Always reset configuration in tests:
+
+```ruby
+after { OxTenderAbstract.reset_configuration! }
+```
+
+## Testing Result Objects
+
+Test both success and failure cases:
+
+```ruby
+it 'returns success result' do
+  result = subject.some_method
+  expect(result).to be_success
+  expect(result.data[:key]).to eq('value')
+end
+
+it 'returns failure result' do
+  result = subject.failing_method
+  expect(result).to be_failure
+  expect(result.error).to include('expected error message')
+end
+```
+
+## Testing Private Methods
+
+Use `send` to test private methods when necessary:
+
+```ruby
+expect(parser.send(:extract_price_from_text, '1000.50')).to eq('1000.50')
+```
+
+## Mock Network Dependencies
+
+Always mock network calls to avoid external dependencies:
+
+```ruby
+before do
+  allow(Net::HTTP).to receive(:new).and_return(mock_http)
+  allow(mock_http).to receive(:request).and_return(mock_response)
+end
+```
+
+## Test Data
+
+Use realistic but minimal test data that covers edge cases:
+
+- Empty/nil values
+- Malformed XML
+- Network errors
+- Large file sizes
+- Invalid configurations
+
+# Testing Patterns
+
+## RSpec Configuration
+
+- Use [spec/spec_helper.rb](mdc:spec/spec_helper.rb) for global test setup
+- Configure RSpec with `--require spec_helper` in [.rspec](mdc:.rspec)
+- Load path includes `lib/` directory for proper module loading
+
+## Test Structure
+
+- One test file per main class: `spec/oxtenderabstract/class_name_spec.rb`
+- Group related tests with `describe` and `context` blocks
+- Use descriptive test names that explain expected behavior
+
+## Mocking Patterns
+
+```ruby
+# Mock external dependencies
+let(:mock_response) { instance_double(Net::HTTPResponse) }
+allow(mock_response).to receive(:is_a?).with(Net::HTTPSuccess).and_return(true)
+allow(mock_response).to receive(:body).and_return('content')
+allow(mock_response).to receive(:[]).with('content-type').and_return('application/zip')
+
+# Mock internal classes
+let(:client_double) { instance_double(OxTenderAbstract::Client) }
+allow(OxTenderAbstract::Client).to receive(:new).and_return(client_double)
+```
+
+## Configuration Reset
+
+Always reset configuration in tests:
+
+```ruby
+after { OxTenderAbstract.reset_configuration! }
+```
+
+## Testing Result Objects
+
+Test both success and failure cases:
+
+```ruby
+it 'returns success result' do
+  result = subject.some_method
+  expect(result).to be_success
+  expect(result.data[:key]).to eq('value')
+end
+
+it 'returns failure result' do
+  result = subject.failing_method
+  expect(result).to be_failure
+  expect(result.error).to include('expected error message')
+end
+```
+
+## Testing Private Methods
+
+Use `send` to test private methods when necessary:
+
+```ruby
+expect(parser.send(:extract_price_from_text, '1000.50')).to eq('1000.50')
+```
+
+## Mock Network Dependencies
+
+Always mock network calls to avoid external dependencies:
+
+```ruby
+before do
+  allow(Net::HTTP).to receive(:new).and_return(mock_http)
+  allow(mock_http).to receive(:request).and_return(mock_response)
+end
+```
+
+## Test Data
+
+Use realistic but minimal test data that covers edge cases:
+
+- Empty/nil values
+- Malformed XML
+- Network errors
+- Large file sizes
+- Invalid configurations

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color