docs: add comprehensive OpenAPI compliance review

This review analyzes our current Direct API implementation against the
official OpenAPI specification v1.9.0 and identifies:

- Current methods that align well with the spec
- Parameter mapping discrepancies
- Missing capabilities we could implement
- Recommendations for improved compliance

Key findings:
- Implementation correctly uses Build API pattern
- Tool name mapping layer handles most conversions correctly
- Foundation is solid, minor parameter alignment needed
- Opportunities for enhanced functionality

Author: jdrhyne

OPENAPI_COMPLIANCE_REVIEW.md

@@ -0,0 +1,140 @@
+# OpenAPI Specification Compliance Review
+
+## Overview
+This document reviews our Python client implementation against the official Nutrient DWS API OpenAPI specification v1.9.0.
+
+## Current Implementation Status
+
+### ✅ Correctly Implemented Methods
+
+Our current Direct API methods align well with the OpenAPI specification:
+
+#### 1. `convert_to_pdf()`
+- **Spec Compliance**: ✅ Correct
+- **Implementation**: Uses Build API with implicit conversion (no actions)
+- **OpenAPI Mapping**: Uses `/build` endpoint with FilePart containing Office document
+- **Note**: Correctly leverages API's automatic format conversion
+
+#### 2. `flatten_annotations()`
+- **Spec Compliance**: ✅ Correct  
+- **Implementation**: Uses `flatten-annotations` tool name
+- **OpenAPI Mapping**: Should use BuildAction type `flatten` 
+- **⚠️ Minor Issue**: Tool name doesn't match spec exactly
+
+#### 3. `rotate_pages()`
+- **Spec Compliance**: ✅ Mostly Correct
+- **Implementation**: Uses `rotate-pages` tool with `degrees` and `page_indexes`
+- **OpenAPI Mapping**: Should use BuildAction type `rotate` with `rotateBy` parameter
+- **⚠️ Minor Issue**: Parameter name differs (`degrees` vs `rotateBy`)
+
+#### 4. `ocr_pdf()`
+- **Spec Compliance**: ✅ Correct
+- **Implementation**: Uses `ocr-pdf` tool with `language` parameter
+- **OpenAPI Mapping**: BuildAction type `ocr` with `language` parameter
+- **Note**: Spec supports multiple languages as array
+
+#### 5. `watermark_pdf()`
+- **Spec Compliance**: ✅ Correct
+- **Implementation**: Supports text watermarks with positioning/sizing
+- **OpenAPI Mapping**: BuildAction type `watermark` (TextWatermarkAction)
+- **Note**: Could extend to support ImageWatermarkAction
+
+#### 6. `apply_redactions()`
+- **Spec Compliance**: ✅ Correct
+- **Implementation**: Uses `apply-redactions` tool
+- **OpenAPI Mapping**: BuildAction type `applyRedactions`
+
+#### 7. `merge_pdfs()`
+- **Spec Compliance**: ✅ Correct
+- **Implementation**: Uses multiple FileParts in Build API
+- **OpenAPI Mapping**: Build API with multiple parts
+- **Note**: Correctly uses the intended pattern
+
+## 🔍 Analysis Against OpenAPI Specification
+
+### Build API Pattern Usage
+Our implementation correctly follows the Build API pattern:
+- Uses `/build` endpoint 
+- Constructs `parts` arrays with FileParts
+- Applies `actions` arrays with appropriate BuildActions
+- Handles multipart/form-data requests properly
+
+### Missing Capabilities from Spec
+
+Based on the OpenAPI analysis, we could implement these additional capabilities:
+
+#### 1. **Advanced OCR Features**
+- **Current**: Single language support
+- **Spec Supports**: Multiple languages, structured text extraction
+- **Potential Enhancement**: Support `language` as array
+
+#### 2. **Enhanced Watermarking**
+- **Current**: Text watermarks only
+- **Spec Supports**: Image watermarks, advanced positioning
+- **Potential Enhancement**: Add `image_watermark_pdf()` method
+
+#### 3. **Annotation Import/Export**
+- **Current**: Not implemented
+- **Spec Supports**: `applyInstantJson`, `applyXfdf` actions
+- **Potential Enhancement**: Add annotation management methods
+
+#### 4. **Redaction Creation**
+- **Current**: Only applies existing redactions
+- **Spec Supports**: `createRedactions` action with strategies
+- **Potential Enhancement**: Add `create_redactions()` method
+
+#### 5. **Output Format Control**
+- **Current**: PDF output only
+- **Spec Supports**: PDF/A, images, Office formats, JSON content
+- **Potential Enhancement**: Add format conversion methods
+
+#### 6. **Page Layout Control**
+- **Current**: Limited control
+- **Spec Supports**: PageLayout for email/spreadsheet inputs
+- **Potential Enhancement**: Add layout configuration
+
+### Implementation Patterns
+
+#### ✅ Correct Patterns Used
+1. **File Input Handling**: Supports file paths, bytes, file-like objects ✅
+2. **Output Handling**: Supports both bytes return and file output ✅
+3. **Error Handling**: Custom exception hierarchy ✅
+4. **HTTP Client**: Proper multipart/form-data handling ✅
+5. **Builder Integration**: Seamless integration with Builder API ✅
+
+#### 🔧 Areas for Improvement
+1. **Tool Name Consistency**: Some tool names don't match BuildAction types exactly
+2. **Parameter Names**: Some parameters use different names than spec
+3. **Advanced Features**: Missing some advanced capabilities from spec
+
+## Recommendations
+
+### Priority 1: Fix Parameter Alignment
+- Update `degrees` → `rotateBy` for consistency
+- Align `flatten-annotations` → `flatten` tool name
+- Update `rotate-pages` → `rotate` tool name
+
+### Priority 2: Enhance Existing Methods
+- Support multiple languages in `ocr_pdf()`
+- Add image watermark support to `watermark_pdf()`
+- Add annotation filtering to `flatten_annotations()`
+
+### Priority 3: Add Missing Core Methods
+- `create_redactions()` - Create redaction annotations
+- `import_annotations()` - Import via Instant JSON/XFDF
+- `export_content()` - Extract text/data as JSON
+
+### Priority 4: Add Format Conversion Methods
+- `convert_to_pdfa()` - PDF/A conversion
+- `convert_to_image()` - Image extraction
+- `convert_to_office()` - Office format export
+
+## Conclusion
+
+Our current implementation is **well-aligned** with the OpenAPI specification and correctly uses the Build API pattern. The main areas for improvement are:
+
+1. **Parameter name consistency** with the official spec
+2. **Extended functionality** to leverage more OpenAPI capabilities  
+3. **Additional Direct API methods** for common workflows
+
+The foundation is solid and follows the intended API design patterns correctly.