feat(document): add support for raw command handling and documentation

[adcondev]

• Introduce new methods for adding raw commands to the document.
• Implement safety checks for potentially dangerous commands in safe mode.
• Enhance the executor to handle raw command execution with format support.
• Add comprehensive documentation for raw command usage and limitations.
• Include tests for raw command handling and validation.

Description

This pull request introduces support for sending raw commands directly to POS printers, enabling advanced and manufacturer-specific operations that are not covered by standard ESC/POS commands. The changes include updates to the API documentation and JSON schema, new code for handling raw commands, convenience methods for common raw operations, and several example documents and usage guides. The implementation also adds a dedicated handler for raw commands and includes new test utilities.

Raw Command Feature Implementation:

• Added support for a new raw command type in the API and JSON schema, allowing users to send arbitrary bytes to the printer with options for format, safety checks, and documentation. [1] [2] [3] [4]
• Implemented builder methods in converter.go for adding raw commands, including convenience functions for cash drawer pulses and beeps, and safety mode enforcement.

Documentation and Examples:

• Added comprehensive documentation (RAW_COMMAND.md) explaining raw command usage, security modes, supported formats, and example escape sequences for common hardware features.
• Provided multiple example JSON documents demonstrating raw command usage for advanced printer features, macro recording, and simple beeper tests. [1] [2] [3]
• Added a Go example (beeper_example.go) showing how to send manufacturer-specific raw commands for hardware features not covered by the standard.

Core Handler and Test Utilities:

• Registered a new handler for raw commands in the document executor, with debug logging for handler registration and improved organization of handler setup.
• Added a mock connector and protocol/profile test utilities for easier testing of raw command execution.

Minor Improvements:

• Added a TODO in the cut handler to improve feed calculation for cutting operations based on dots rather than lines.

These changes collectively make the library more flexible and suitable for advanced use cases, while also providing safety mechanisms and clear documentation for developers.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation only
• 🔧 Configuration/DevOps
• ♻️ Code refactoring
• 📦 Dependency update
• ⚡ Performance improvement
• 🧪 Test addition/modification

Component(s) Affected

• composer - ESC/POS protocol composer
• connection - Printer connections
• commands - ESC/POS command implementations
• document - Document processing
• graphics - Image processing
• printer - Barcode generation
• profile - Printer profiles
• service - High-level printer service
• github - GitHub related files and workflows

How Has This Been Tested?

• Unit tests pass locally
• Integration tests pass
• Manual testing with physical printer
• Examples built and run successfully
• N/A (documentation/configuration only)

Test Configuration

• Go Version:
• OS:
• Printer Model (if applicable):

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Screenshots/Examples

Breaking Changes

Additional Notes

[github-actions]

👋 Thanks for opening this PR, @adcondev!

Here's what will happen next:

• 🤖 Automated checks will run
• 🏷️ Labels will be added automatically
• 👀 A maintainer will review your changes

Please make sure:

• ✅ All tests pass
• 📝 The PR title follows conventional commits
• 📋 The PR template is filled out completely

[Copilot]

Pull request overview

This PR introduces comprehensive support for sending raw ESC/POS commands directly to POS printers, enabling advanced manufacturer-specific operations beyond the standard command set. The implementation includes safety mechanisms to prevent dangerous commands in safe mode, multiple input format support (hex, base64), and extensive documentation with practical examples.

Key changes:

• Added raw command handler with safety validation for dangerous command patterns
• Implemented builder methods for raw command construction with convenience wrappers (cash drawer pulse, beeper)
• Comprehensive test coverage for hex parsing, command validation, and execution scenarios

Reviewed changes

Copilot reviewed 14 out of 18 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pkg/document/raw_handler.go	Core raw command handler with format parsing, safety checks, and bidirectional command detection
pkg/document/raw_handler_test.go	Extensive test suite covering hex parsing, validation, safe mode, and edge cases
pkg/document/converter.go	Builder methods for adding raw commands with safety mode options and convenience methods
pkg/document/executor.go	Handler registration for raw commands with debug logging
pkg/document/handlers.go	Added TODO comment for improving cut feed calculation
internal/testutils/handler_helpers.go	Mock connector and test utilities for raw command testing
pkg/service/escpos_printer.go	Added commented beep configuration for printer initialization
docs/RAW_COMMAND.md	Comprehensive documentation on raw command usage, limitations, and security
api/v1/document.schema.json	JSON schema definition for raw command type
api/v1/DOCUMENT_V1.md	API documentation for raw command with examples
examples/beeper/beeper_example.go	Go example demonstrating manufacturer-specific beeper command
examples/document/raw/*.json	JSON examples for simple beeper, advanced features, and kiosk turnos
examples/document/tickets/*.json	Sample ticket documents (not related to raw commands)
.gitignore	Updated to allow new documentation files

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.