patent_odp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e98c0359a5ab7545b88c5f13ea0773d6bd84956daaa4b4cf200d1fdbeb82fe07
+  data.tar.gz: 2d6c66fe82ed82623f0fb1a9fd44c8400a058b343e633fad1dff0f21e4d483b9
+SHA512:
+  metadata.gz: 38759c72bf38b3a9ea7152fcd4863210a35851ee469b817fcb6e88ba8345991d353b0ecb7a5d1fe529fba7094e2296ab0b5f62630c1f9cd9e9dcc68ed047801a
+  data.tar.gz: 07f2d0c94b876b006fb679b69d77efd503453f3aea06fd79c8239c69ccc8282a661dc726f87c55e741fdc536f625a179deb59c194be7e2398b09f8d640fa3f72

data/CHANGELOG.md

@@ -0,0 +1,139 @@
+# 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]
+
+### Planned
+- Search API support
+- Document retrieval
+- Transaction history
+- Assignment data
+- Pagination support
+
+See [ROADMAP.md](ROADMAP.md) for detailed future plans.
+
+## [0.1.0] - 2024-10-16
+
+### Added
+
+#### Core Features
+- Application metadata retrieval by application number via `Client#application`
+- `PatentODP::Client` class for HTTP communication with USPTO API
+- `PatentODP::Application` class representing patent application data with clean Ruby API
+- Global configuration via `PatentODP.configure`
+- Per-client configuration override support
+
+#### Application Data Access
+- `Application#id` - Application number
+- `Application#title` - Patent/application title
+- `Application#patent_number` - Patent number if granted
+- `Application#filing_date` - Filing date (Date object)
+- `Application#status` - Application status
+- `Application#status_date` - Status date (Date object)
+- `Application#early_publication_number` - Publication number
+- `Application#early_publication_date` - Publication date (Date object)
+- `Application#inventors` - Array of inventor names
+- `Application#applicants` - Array of applicant names
+- `Application#patented?` - Boolean helper for patent status
+- `Application#to_h` - Access raw API response data
+- `Application#inspect` - Human-readable string representation
+
+#### Configuration Options
+- `api_key` - USPTO API key (required)
+- `timeout` - HTTP request timeout in seconds (default: 30)
+- `retry_enabled` - Enable/disable automatic retry logic (default: true)
+- `base_url` - API base URL (read-only, set to USPTO endpoint)
+
+#### Error Handling
+- `PatentODP::Error` - Base error class
+- `PatentODP::ConfigurationError` - Configuration validation errors
+- `PatentODP::APIError` - Base class for API-related errors
+- `PatentODP::ClientError` - 4xx HTTP errors
+- `PatentODP::ServerError` - 5xx HTTP errors
+- `PatentODP::UnauthorizedError` - 401 authentication errors
+- `PatentODP::NotFoundError` - 404 not found errors
+- `PatentODP::RateLimitError` - 429 rate limit errors
+
+#### Security Features
+- Input validation for application numbers to prevent path traversal attacks
+- Character whitelist validation (alphanumeric, underscore, hyphen only)
+- Type safety checks for all configuration values
+- API key validation before requests
+- Timeout value validation (must be positive number)
+- Protection against non-string API keys
+- Defensive nil checks throughout
+
+#### Developer Experience
+- Automatic date parsing (converts strings to Ruby `Date` objects)
+- Snake_case method names following Ruby conventions
+- Detailed YARD documentation
+- Helpful error messages with configuration hints
+- Clean, chainable API design
+
+#### HTTP Client Features
+- Built on Faraday for reliable HTTP communication
+- Automatic retry logic for transient failures (429, 5xx errors)
+- Configurable retry behavior (max: 3, with exponential backoff)
+- Proper timeout handling (connect and read timeouts)
+- HTTPS-only communication
+- API key sent via `X-API-KEY` header
+
+#### Testing
+- 72 comprehensive test cases
+- 98%+ code coverage with SimpleCov
+- Unit tests for all components
+- Integration tests with mocked API responses
+- Security tests for input validation
+- Error handling tests
+- WebMock integration for reliable HTTP testing
+- Fast test suite (< 0.05 seconds)
+
+#### Documentation
+- Comprehensive README with usage examples
+- Rails integration examples
+- Error handling guide
+- Security best practices
+- ROADMAP documenting planned features
+- Inline code documentation with YARD
+
+#### Dependencies
+- `faraday` (~> 2.0) - HTTP client
+- `faraday-retry` (~> 2.0) - Automatic retry middleware
+- Development: `rspec`, `webmock`, `rubocop`, `simplecov`
+
+### Technical Details
+
+#### API Coverage
+- `GET /api/v1/patent/applications/{application_number}` - Retrieve application metadata
+
+#### Ruby Version
+- Requires Ruby >= 3.2.0
+- Tested on Ruby 3.4.x
+
+#### Performance
+- Default 30-second timeout
+- Configurable connection and read timeouts
+- Optional retry logic can be disabled for faster failures in tests
+
+### Security
+
+#### Vulnerability Fixes
+- Fixed path traversal vulnerability in application number handling
+- Added input validation regex to prevent injection attacks
+- Added type checking to prevent NoMethodError on invalid inputs
+- Added JSON parsing error handling
+- Protected against malformed API responses
+
+#### Best Practices
+- HTTPS-only communication
+- No secrets logged or exposed in errors
+- API keys passed via headers (not URL)
+- Comprehensive input validation
+- Safe error messages that don't leak internal details
+
+[unreleased]: https://github.com/zalepa/patent_odp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/zalepa/patent_odp/releases/tag/v0.1.0

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 George Zalepa
+
+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/README.md

@@ -0,0 +1,392 @@
+# PatentODP
+
+A Ruby gem for interacting with the USPTO's Open Data Portal (ODP) API. This gem provides a clean, idiomatic Ruby interface to access patent file wrapper data including application metadata, documents, and more.
+
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)]()
+[![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen)]()
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.2.0-blue)]()
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [Basic Usage](#basic-usage)
+  - [Working with Applications](#working-with-applications)
+  - [Error Handling](#error-handling)
+  - [Advanced Configuration](#advanced-configuration)
+- [Security](#security)
+- [Development](#development)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+### Currently Implemented ✅
+
+- **Application Metadata Retrieval** - Fetch detailed patent application information by application number
+- **Clean Ruby API** - Idiomatic Ruby interface with snake_case methods and automatic date parsing
+- **Comprehensive Error Handling** - Specific error classes for different failure modes
+- **Input Validation** - Protection against path traversal and injection attacks
+- **Automatic Retries** - Built-in retry logic for transient failures (configurable)
+- **Type Safety** - Robust validation of all inputs
+- **Well Tested** - 72+ test cases with 98%+ code coverage
+
+### Planned Features 🚧
+
+See [ROADMAP.md](ROADMAP.md) for upcoming features including:
+- Search API support
+- Document retrieval
+- Transaction history
+- Assignment data
+- Pagination support
+- Bulk operations
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'patent_odp'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install patent_odp
+```
+
+## Configuration
+
+### Getting an API Key
+
+You'll need a USPTO API key to use this gem. Get one for free at:
+[https://data.uspto.gov/apis/getting-started](https://data.uspto.gov/apis/getting-started)
+
+### Basic Configuration
+
+Configure the gem with your API key:
+
+```ruby
+require 'patent_odp'
+
+PatentODP.configure do |config|
+  config.api_key = 'your_api_key_here'
+end
+```
+
+### Using Environment Variables
+
+For security, store your API key in an environment variable:
+
+```ruby
+# In your .env or environment
+# USPTO_API_KEY=your_api_key_here
+
+PatentODP.configure do |config|
+  config.api_key = ENV['USPTO_API_KEY']
+end
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'patent_odp'
+
+# Configure the gem
+PatentODP.configure do |config|
+  config.api_key = ENV['USPTO_API_KEY']
+end
+
+# Create a client
+client = PatentODP::Client.new
+
+# Fetch application data
+app = client.application("16123456")
+
+# Access application data
+puts app.title
+# => "LEARNING ASSISTANCE DEVICE, METHOD OF OPERATING LEARNING ASSISTANCE DEVICE..."
+
+puts app.patent_number
+# => "10902286"
+
+puts app.status
+# => "Patented Case"
+```
+
+### Working with Applications
+
+The `Application` object provides clean, Ruby-friendly access to patent data:
+
+```ruby
+app = client.application("16123456")
+
+# Basic Information
+app.id                        # => "16123456"
+app.title                     # => "Patent title"
+app.patent_number             # => "10902286"
+
+# Dates (automatically parsed as Date objects)
+app.filing_date               # => #<Date: 2018-09-06>
+app.status_date               # => #<Date: 2021-01-06>
+app.early_publication_date    # => #<Date: 2019-03-28>
+
+# Status Information
+app.status                    # => "Patented Case"
+app.patented?                 # => true (boolean helper)
+
+# Publication Information
+app.early_publication_number  # => "US20190095759A1"
+
+# People (returns Arrays)
+app.inventors                 # => ["Shoji KANADA"]
+app.applicants                # => ["FUJIFILM Corporation"]
+
+# Raw data access
+app.to_h                      # => Full hash from API
+app.inspect                   # => Human-readable representation
+```
+
+### Error Handling
+
+The gem provides specific error classes for different failure modes:
+
+```ruby
+begin
+  app = client.application("invalid")
+rescue PatentODP::NotFoundError
+  puts "Application not found"
+rescue PatentODP::UnauthorizedError
+  puts "Invalid API key"
+rescue PatentODP::RateLimitError
+  puts "Rate limit exceeded - try again later"
+rescue PatentODP::ServerError => e
+  puts "Server error: #{e.message}"
+rescue PatentODP::APIError => e
+  puts "API error: #{e.message}"
+rescue ArgumentError => e
+  puts "Invalid input: #{e.message}"
+end
+```
+
+#### Error Types
+
+- `PatentODP::ConfigurationError` - Invalid or missing configuration
+- `PatentODP::UnauthorizedError` - Invalid API key (401)
+- `PatentODP::NotFoundError` - Application not found (404)
+- `PatentODP::RateLimitError` - Rate limit exceeded (429)
+- `PatentODP::ServerError` - Server errors (5xx)
+- `PatentODP::APIError` - Base class for all API errors
+- `ArgumentError` - Invalid input (e.g., malformed application number)
+
+### Advanced Configuration
+
+#### Custom Timeouts
+
+```ruby
+PatentODP.configure do |config|
+  config.api_key = ENV['USPTO_API_KEY']
+  config.timeout = 60  # seconds (default: 30)
+end
+```
+
+#### Disabling Retries
+
+By default, the client retries failed requests (429, 5xx errors). You can disable this:
+
+```ruby
+# Globally
+PatentODP.configure do |config|
+  config.api_key = ENV['USPTO_API_KEY']
+  config.retry_enabled = false
+end
+
+# Per-client
+client = PatentODP::Client.new(retry_enabled: false)
+```
+
+#### Per-Client Configuration
+
+Override global settings for specific clients:
+
+```ruby
+# Use global config for most things, but custom timeout for this client
+client = PatentODP::Client.new(timeout: 120)
+
+# Or completely custom client
+client = PatentODP::Client.new(
+  api_key: 'different_key',
+  timeout: 90,
+  retry_enabled: false
+)
+```
+
+### Rails Integration
+
+In a Rails application, configure in an initializer:
+
+```ruby
+# config/initializers/patent_odp.rb
+PatentODP.configure do |config|
+  config.api_key = Rails.application.credentials.dig(:uspto, :api_key)
+  config.timeout = 30
+end
+```
+
+Then use in your models or controllers:
+
+```ruby
+class Patent < ApplicationRecord
+  def fetch_metadata
+    client = PatentODP::Client.new
+    app = client.application(self.application_number)
+
+    update!(
+      title: app.title,
+      patent_number: app.patent_number,
+      filing_date: app.filing_date,
+      status: app.status
+    )
+  rescue PatentODP::NotFoundError
+    Rails.logger.warn("Application #{application_number} not found")
+  end
+end
+```
+
+## Security
+
+This gem implements several security best practices:
+
+- ✅ **Input Validation** - All application numbers are validated to prevent path traversal and injection attacks
+- ✅ **HTTPS Only** - All API requests use HTTPS
+- ✅ **No Secret Logging** - API keys are never logged or exposed in error messages
+- ✅ **Type Safety** - All inputs are validated for correct types
+- ✅ **Error Sanitization** - Error messages don't expose internal implementation details
+- ✅ **Dependency Security** - Uses well-maintained libraries (Faraday)
+
+### Best Practices
+
+1. **Never commit API keys** - Use environment variables or Rails credentials
+2. **Validate application numbers** - Before passing user input to the API
+3. **Handle rate limits** - Implement backoff strategies in production
+4. **Monitor errors** - Track API errors in your application monitoring
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then:
+
+```bash
+# Run tests
+rake spec
+
+# Run linter
+rake rubocop
+
+# Auto-fix linting issues (safe corrections only)
+rake rubocop:autocorrect
+
+# Auto-fix all linting issues (including unsafe corrections)
+rake rubocop:autocorrect_all
+
+# Run both tests and linter (default)
+rake
+
+# View coverage report (automatically generated)
+open coverage/index.html
+```
+
+### Running Tests
+
+The test suite includes:
+- Unit tests for all components
+- Integration tests with mocked API responses
+- Security tests for input validation
+- Error handling tests
+
+```bash
+# All tests
+rake spec
+
+# Specific file
+rspec spec/patent_odp/client_spec.rb
+
+# Specific test
+rspec spec/patent_odp/client_spec.rb:30
+```
+
+### Interactive Console
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment:
+
+```bash
+bin/console
+
+# In the console:
+PatentODP.configure { |c| c.api_key = "your_key" }
+client = PatentODP::Client.new
+app = client.application("16123456")
+```
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for planned features and enhancements.
+
+## API Documentation
+
+The USPTO Open Data Portal provides access to:
+
+- **100+ data attributes** for patent applications
+- **Daily data refreshes** from USPTO systems
+- **Historical data** back to 2001
+- **File wrapper documents** including office actions, responses, and more
+
+For complete API documentation, visit:
+- [USPTO Open Data Portal](https://data.uspto.gov/)
+- [API Documentation](https://data.uspto.gov/apis/patent-file-wrapper/search)
+- [Getting Started Guide](https://data.uspto.gov/apis/getting-started)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/zalepa/patent_odp. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/zalepa/patent_odp/blob/main/CODE_OF_CONDUCT.md).
+
+### Development Guidelines
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Write tests for your changes
+4. Ensure all tests pass (`rake spec`)
+5. Ensure code style compliance (`rubocop`)
+6. Commit your changes (`git commit -am 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Create a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the PatentODP project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/zalepa/patent_odp/blob/main/CODE_OF_CONDUCT.md).
+
+## Acknowledgments
+
+- [USPTO Open Data Portal](https://data.uspto.gov/) for providing the API
+- Built with [Faraday](https://github.com/lostisland/faraday) for HTTP requests
+
+## Support
+
+- 📚 [Documentation](https://github.com/zalepa/patent_odp)
+- 🐛 [Issue Tracker](https://github.com/zalepa/patent_odp/issues)
+- 💬 [Discussions](https://github.com/zalepa/patent_odp/discussions)

data/ROADMAP.md

@@ -0,0 +1,189 @@
+# PatentODP Roadmap
+
+This document outlines the development roadmap for PatentODP, including completed features and planned enhancements.
+
+## Version 0.1.0 (Current) ✅
+
+**Status**: Released
+**Focus**: Core application metadata retrieval with robust error handling and security
+
+### Completed Features
+
+- ✅ Application metadata retrieval by application number
+- ✅ Clean, idiomatic Ruby API with snake_case methods
+- ✅ Automatic date parsing (returns Ruby `Date` objects)
+- ✅ Comprehensive error handling with specific error classes
+- ✅ Input validation to prevent path traversal attacks
+- ✅ Configurable automatic retry logic
+- ✅ Type safety throughout the codebase
+- ✅ Full test coverage (72+ tests)
+- ✅ Security hardening and validation
+
+### API Coverage
+
+- ✅ `GET /api/v1/patent/applications/{application_number}` - Application metadata
+
+## Version 0.2.0 (Planned) 🚧
+
+**Status**: Planning
+**Focus**: Search capabilities and pagination
+
+### Planned Features
+
+- 🚧 **Search API Support**
+  - Basic keyword search across patent applications
+  - Field-specific searches (title, inventor, assignee, etc.)
+  - Date range filtering
+  - Result pagination
+  - Search result object with metadata
+
+- 🚧 **Pagination Support**
+  - Automatic pagination handling
+  - Configurable page sizes
+  - Iterator/Enumerator pattern for large result sets
+
+- 🚧 **Enhanced Application Methods**
+  - Additional metadata fields (CPC classifications, etc.)
+  - Better handling of complex nested data structures
+
+### API Coverage
+
+- 🚧 `GET /api/v1/patent/applications/search` - Search applications
+
+## Version 0.3.0 (Planned) 📋
+
+**Status**: Planning
+**Focus**: Document retrieval and file wrapper data
+
+### Planned Features
+
+- 📋 **Document Retrieval**
+  - Fetch list of documents for an application
+  - Download individual documents
+  - Document metadata (type, date, description)
+  - Binary/PDF download support
+
+- 📋 **Transaction History**
+  - Retrieve transaction/event history for applications
+  - Filter by event type
+  - Timeline view of application lifecycle
+
+- 📋 **Document Types**
+  - Office actions
+  - Applicant responses
+  - Notices
+  - Certificates
+  - Correspondence
+
+### API Coverage
+
+- 📋 `GET /api/v1/patent/applications/{application_number}/documents` - List documents
+- 📋 `GET /api/v1/patent/applications/{application_number}/documents/{document_id}` - Download document
+- 📋 `GET /api/v1/patent/applications/{application_number}/transactions` - Transaction history
+
+## Version 0.4.0 (Planned) 📄
+
+**Status**: Planning
+**Focus**: Assignment data and ownership information
+
+### Planned Features
+
+- 📄 **Assignment Search**
+  - Search assignments by assignee, assignor, or patent number
+  - Assignment history for applications
+  - Ownership chain tracking
+
+- 📄 **Assignment Details**
+  - Recording date and execution date
+  - Assignor and assignee information
+  - Conveyance type
+  - Reel and frame numbers
+
+### API Coverage
+
+- 📄 `GET /api/v1/patent/applications/{application_number}/assignments` - Assignment data
+- 📄 Assignment search endpoints
+
+## Version 1.0.0 (Future) 🎯
+
+**Status**: Planning
+**Focus**: Production readiness, performance, and advanced features
+
+### Planned Features
+
+- 🎯 **Bulk Operations**
+  - Batch application retrieval
+  - Parallel requests with connection pooling
+  - Rate limit aware batching
+
+- 🎯 **Caching Layer**
+  - Optional Redis/Memcached integration
+  - Configurable TTL
+  - Cache invalidation strategies
+
+- 🎯 **Advanced Search**
+  - OpenSearch query DSL support
+  - Complex boolean queries
+  - Faceted search
+  - Aggregations
+
+- 🎯 **Webhook Support**
+  - Subscribe to application updates (if supported by API)
+
+- 🎯 **Performance Optimizations**
+  - Connection pooling
+  - HTTP/2 support
+  - Streaming for large responses
+  - Async/concurrent request support
+
+- 🎯 **Developer Tools**
+  - CLI tool for quick queries
+  - Debug mode with request/response logging
+  - API usage analytics
+
+## Future Considerations 💭
+
+Features under consideration for future versions:
+
+- **Trademark Support** - If USPTO ODP expands to trademarks
+- **Export Utilities** - CSV, JSON, XML export of search results
+- **Data Analysis Tools** - Helper methods for patent portfolio analysis
+- **GraphQL API** - Alternative query interface
+- **ActiveRecord Integration** - Optional Rails/ActiveRecord helpers
+- **Monitoring & Observability** - Built-in metrics and tracing
+
+## Contributing
+
+We welcome contributions! If you'd like to work on any of these features:
+
+1. Check the [issue tracker](https://github.com/zalepa/patent_odp/issues) for related issues
+2. Comment on the issue or create a new one to discuss your approach
+3. Fork the repository and create a feature branch
+4. Submit a pull request with tests and documentation
+
+## Feedback
+
+Have ideas for features not listed here? We'd love to hear from you!
+
+- Open an issue: https://github.com/zalepa/patent_odp/issues
+- Start a discussion: https://github.com/zalepa/patent_odp/discussions
+
+## Release Schedule
+
+We aim for:
+- **Minor versions** (0.x.0) every 2-3 months with new features
+- **Patch versions** (0.x.y) as needed for bug fixes and security updates
+- **Major version** (1.0.0) when API is stable and production-ready
+
+## Version History
+
+### 0.1.0 - Initial Release
+- Application metadata retrieval
+- Error handling and validation
+- Security hardening
+- Test coverage
+
+---
+
+Last Updated: 2024-10-16
+Current Version: 0.1.0

data/Rakefile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+# Auto-correct RuboCop offenses
+RuboCop::RakeTask.new("rubocop:autocorrect") do |task|
+  task.options = ["--autocorrect"]
+end
+
+# Auto-correct all RuboCop offenses (including unsafe)
+RuboCop::RakeTask.new("rubocop:autocorrect_all") do |task|
+  task.options = ["--autocorrect-all"]
+end
+
+task default: %i[spec rubocop]

data/lib/patent_odp/application.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "date"
+
+module PatentODP
+  # Represents a patent application with metadata from the USPTO API
+  class Application
+    # @return [Hash] Raw application data from API
+    attr_reader :data
+
+    # @param data [Hash] Raw application data from API response
+    # @param application_number [String, nil] Application number from request
+    def initialize(data, application_number = nil)
+      @data = data
+      @metadata = data["applicationMetaData"] || {}
+      @application_number = application_number
+    end
+
+    # @return [String, nil] Application ID
+    def id
+      @application_number
+    end
+
+    # @return [String, nil] Patent number if granted
+    def patent_number
+      @metadata["patentNumber"]
+    end
+
+    # @return [String, nil] Patent/Application title
+    def title
+      @metadata["inventionTitle"]
+    end
+
+    # @return [Date, nil] Filing date
+    def filing_date
+      parse_date(@metadata["filingDate"])
+    end
+
+    # @return [String, nil] Application status
+    def status
+      @metadata["applicationStatusDescriptionText"]
+    end
+
+    # @return [Date, nil] Status date
+    def status_date
+      parse_date(@metadata["applicationStatusDate"])
+    end
+
+    # @return [String, nil] Early publication number
+    def early_publication_number
+      @metadata["earliestPublicationNumber"]
+    end
+
+    # @return [Date, nil] Early publication date
+    def early_publication_date
+      parse_date(@metadata["earliestPublicationDate"])
+    end
+
+    # @return [Array<String>] List of applicant names
+    def applicants
+      extract_names(@metadata["applicantBag"], "applicantNameText")
+    end
+
+    # @return [Array<String>] List of inventor names
+    def inventors
+      extract_names(@metadata["inventorBag"], "inventorNameText")
+    end
+
+    # @return [Boolean] Whether the application has been granted
+    def patented?
+      status&.include?("Patented") || false
+    end
+
+    # @return [Hash] Raw data hash
+    def to_h
+      @data
+    end
+
+    # @return [String] Human-readable representation
+    def inspect
+      "#<PatentODP::Application id=#{id.inspect} title=#{title.inspect}>"
+    end
+
+    private
+
+    # Parse date string to Date object
+    # @param date_string [String, nil]
+    # @return [Date, nil]
+    def parse_date(date_string)
+      return nil if date_string.nil? || date_string.empty?
+
+      Date.parse(date_string)
+    rescue ArgumentError
+      nil
+    end
+
+    # Extract names from nested API structure
+    # @param items [Array, nil] Array of items with name fields
+    # @param name_field [String] Name of the field containing names
+    # @return [Array<String>]
+    def extract_names(items, name_field)
+      return [] if items.nil?
+
+      Array(items).map { |item| item[name_field] if item.is_a?(Hash) }.compact
+    end
+  end
+end

data/lib/patent_odp/client.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module PatentODP
+  # HTTP client for interacting with the USPTO Open Data Portal API
+  class Client
+    BASE_URL = "https://api.uspto.gov/api/v1/patent/applications"
+
+    # @param api_key [String, nil] API key for authentication. If nil, uses global config.
+    # @param timeout [Integer, nil] Request timeout in seconds. If nil, uses global config.
+    # @param retry_enabled [Boolean, nil] Enable retry logic. If nil, uses global config.
+    def initialize(api_key: nil, timeout: nil, retry_enabled: nil)
+      @api_key = api_key || PatentODP.configuration.api_key!
+      @timeout = timeout || PatentODP.configuration.timeout
+      @retry_enabled = retry_enabled.nil? ? PatentODP.configuration.retry_enabled : retry_enabled
+      @connection = build_connection
+    end
+
+    # Fetch application metadata by application number
+    # @param application_number [String] The patent application number
+    # @return [Application] Application object with metadata
+    # @raise [NotFoundError] if application doesn't exist
+    # @raise [UnauthorizedError] if API key is invalid
+    # @raise [RateLimitError] if rate limit is exceeded
+    # @raise [ServerError] for server errors
+    # @raise [ArgumentError] if application_number is invalid
+    def application(application_number)
+      validate_application_number!(application_number)
+
+      response = @connection.get(application_number) do |req|
+        req.headers["X-API-KEY"] = @api_key
+      end
+
+      handle_response(response, application_number)
+    end
+
+    private
+
+    # Validate application number to prevent path traversal and injection attacks
+    # @param application_number [String] The application number to validate
+    # @raise [ArgumentError] if application_number is invalid
+    def validate_application_number!(application_number)
+      raise ArgumentError, "Application number cannot be nil" if application_number.nil?
+      raise ArgumentError, "Application number must be a string" unless application_number.is_a?(String)
+      raise ArgumentError, "Application number cannot be empty" if application_number.strip.empty?
+
+      # Application numbers should only contain alphanumeric characters and basic punctuation
+      # This prevents path traversal attacks like "../../../etc/passwd"
+      return if application_number.match?(/\A[\w-]+\z/)
+
+      raise ArgumentError,
+            "Application number contains invalid characters. Only alphanumeric, underscore, and hyphen allowed."
+    end
+
+    def build_connection
+      Faraday.new(url: BASE_URL) do |conn|
+        if @retry_enabled
+          conn.request :retry, {
+            max: 3,
+            interval: 0.5,
+            backoff_factor: 2,
+            retry_statuses: [429, 500, 502, 503, 504]
+          }
+        end
+        conn.adapter Faraday.default_adapter
+        conn.options.timeout = @timeout
+        conn.options.open_timeout = 10
+      end
+    end
+
+    def handle_response(response, application_number)
+      case response.status
+      when 200
+        parse_application_response(response, application_number)
+      when 401
+        raise UnauthorizedError, "Invalid API key"
+      when 404
+        raise NotFoundError, "Application not found"
+      when 429
+        raise RateLimitError, "API rate limit exceeded"
+      when 500..599
+        raise ServerError, "Server error: #{response.status}"
+      else
+        raise APIError, "Unexpected response: #{response.status}"
+      end
+    end
+
+    def parse_application_response(response, application_number)
+      data = JSON.parse(response.body)
+
+      # Navigate the nested structure to get application data
+      wrapper_bag = data["patentFileWrapperDataBag"]
+      return Application.new({}, application_number) if wrapper_bag.nil? || wrapper_bag.empty?
+
+      # Get the first (and should be only) item in the bag
+      wrapper_data = wrapper_bag.first
+      return Application.new({}, application_number) unless wrapper_data
+
+      # Extract the application metadata
+      app_metadata = wrapper_data["applicationMetaData"]
+      return Application.new({}, application_number) unless app_metadata
+
+      # Pass the full wrapper data so Application can access events, etc if needed
+      Application.new(wrapper_data, application_number)
+    rescue JSON::ParserError => e
+      raise APIError, "Failed to parse API response: #{e.message}"
+    end
+  end
+end

data/lib/patent_odp/configuration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PatentODP
+  # Configuration class for PatentODP gem
+  # Handles API key, base URL, and other configurable options
+  class Configuration
+    attr_accessor :api_key, :retry_enabled
+    attr_reader :base_url, :timeout
+
+    def initialize(api_key: nil, timeout: nil, retry_enabled: nil)
+      @api_key = api_key
+      @base_url = "https://api.uspto.gov/api/v1/patent/applications"
+      self.timeout = timeout || 30
+      @retry_enabled = retry_enabled.nil? || retry_enabled
+    end
+
+    # Set timeout with validation
+    # @param value [Integer] Timeout in seconds
+    # @raise [ArgumentError] if timeout is invalid
+    def timeout=(value)
+      raise ArgumentError, "Timeout must be a positive number" if value && (!value.is_a?(Numeric) || value <= 0)
+
+      @timeout = value
+    end
+
+    # Returns the API key if set, raises an error otherwise
+    # @return [String] the API key
+    # @raise [ConfigurationError] if API key is not set or is blank
+    def api_key!
+      if @api_key.nil? || !@api_key.is_a?(String) || @api_key.strip.empty?
+        raise ConfigurationError,
+              "API key is required. Set it with PatentODP.configure { |c| c.api_key = 'your_key' }"
+      end
+      @api_key
+    end
+  end
+end

data/lib/patent_odp/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PatentODP
+  # Base error class for all PatentODP errors
+  class Error < StandardError; end
+
+  # Raised when configuration is invalid or missing
+  class ConfigurationError < Error; end
+
+  # Raised when API request fails
+  class APIError < Error; end
+
+  # Raised when API returns 4xx error
+  class ClientError < APIError; end
+
+  # Raised when API returns 5xx error
+  class ServerError < APIError; end
+
+  # Raised when API returns 401 Unauthorized
+  class UnauthorizedError < ClientError; end
+
+  # Raised when API returns 404 Not Found
+  class NotFoundError < ClientError; end
+
+  # Raised when API returns 429 Too Many Requests
+  class RateLimitError < ClientError; end
+end

data/lib/patent_odp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PatentODP
+  VERSION = "0.1.0"
+end

data/lib/patent_odp.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "patent_odp/version"
+require_relative "patent_odp/errors"
+require_relative "patent_odp/configuration"
+require_relative "patent_odp/application"
+require_relative "patent_odp/client"
+
+module PatentODP
+  class << self
+    # Returns the global configuration object
+    # @return [Configuration] the configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration object for setup
+    # @yield [Configuration] the configuration instance
+    # @example
+    #   PatentODP.configure do |config|
+    #     config.api_key = "your_api_key"
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Resets the configuration to a fresh instance
+    # Primarily used for testing
+    # @return [Configuration] the new configuration instance
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/sig/patent_odp.rbs

@@ -0,0 +1,4 @@
+module PatentOdp
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: patent_odp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- George Zalepa
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A Ruby gem for interacting with the USPTO's Open Data Portal API, providing
+  access to patent file wrapper data.
+email:
+- george.zalepa@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- ROADMAP.md
+- Rakefile
+- lib/patent_odp.rb
+- lib/patent_odp/application.rb
+- lib/patent_odp/client.rb
+- lib/patent_odp/configuration.rb
+- lib/patent_odp/errors.rb
+- lib/patent_odp/version.rb
+- sig/patent_odp.rbs
+homepage: https://github.com/zalepa/patent_odp
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/zalepa/patent_odp
+  source_code_uri: https://github.com/zalepa/patent_odp
+  changelog_uri: https://github.com/zalepa/patent_odp/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby wrapper for the USPTO Open Data Portal (ODP) API
+test_files: []