sat_mx 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecf0432037eb033ade4de9f89e9d9edfcd4a7174391758d2c1dc47c5771e44b0
-  data.tar.gz: 0aaf19d6965d16cc6c28047964fe4d00be5c925e9cc921f37f3e86985f50993e
+  metadata.gz: 24d8984a200bf9e2d95a2fcb90e10097f54a4ed496e418c3880df1848dd5c302
+  data.tar.gz: 01a221e8d1bcab95919dc4990677ca9c63bc775e1e1f03281c5c07be2653805c
 SHA512:
-  metadata.gz: 21ce855b92d37223820e13056c03468880473bd0a791987d2ba8adc65c7d6da11f5f058a52a7d2f3ca26b1cd4d2434c1308cd9e3f10235add7d6ab9a1b7c5a98
-  data.tar.gz: 8a5b7724f51b3698d1a71b15da5e75fa905082ce7b631d261e2c20fec9f0cc47fb4ea4f2992012437afc94759ae419b34b4aa565f79bace0ca1f8632eed97084
+  metadata.gz: 3e1905940a68f281204884f848fea09806e6cc7ce242389aba92154e95777d5563b0b400dd731832982f824c626f4353bf204138f75a5ca26b1f4db063adabbe
+  data.tar.gz: 3535c79dafbb37cc18fc887a3d266a7ce9f1474e4f0d5add1ae6cfae652c88e64dd72b7fc73867c4d9a82b941c5179a2f447943df63170ee8ad01a0c69f1e18c

data/README.md

@@ -1,39 +1,98 @@
 # SatMx
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/sat_mx`. To experiment with that code, run `bin/console` for an interactive prompt.
+Ruby client for SAT (Mexican Tax Administration) web services to download CFDI invoices.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+```bash
+gem install sat_mx
+```
 
-Install the gem and add to the application's Gemfile by executing:
+Or add to your Gemfile:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+gem "sat_mx"
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Configuration
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+SatMx.configure do |config|
+  config[:certificate] = "path/to/certificate.cer"
+  config[:private_key] = "path/to/private.key"
+  config[:password] = "key_password"
+end
+```
 
 ## Usage
 
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/sat_mx. 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/[USERNAME]/sat_mx/blob/master/CODE_OF_CONDUCT.md).
+```ruby
+# 1. Authenticate
+result = SatMx.authenticate
+raise "Auth failed" unless result.success?
+
+token = result.value
+
+# 2. Request download
+result = SatMx.download_request(
+  start_date: Time.new(2024, 1, 1),
+  end_date: Time.new(2024, 1, 31),
+  request_type: :cfdi,
+  issuing_rfc: "ABC010101ABC",
+  recipient_rfcs: ["XYZ020202XYZ"],
+  requester_rfc: "ABC010101ABC",
+  access_token: token
+)
+raise "Request failed" unless result.success?
+
+request_id = result.value
+
+# 3. Verify status (poll until ready)
+loop do
+  result = SatMx.verify_request(
+    request_id: request_id,
+    requester_rfc: "ABC010101ABC",
+    access_token: token
+  )
+
+  case result.value[:request_status]
+  when :finished
+    break result.value[:package_ids]
+  when :error, :rejected, :expired
+    raise "Request failed: #{result.value}"
+  end
+
+  sleep 5
+end
+
+# 4. Download packages
+package_ids.each do |package_id|
+  result = SatMx.download_petition(
+    package_id: package_id,
+    requester_rfc: "ABC010101ABC",
+    access_token: token
+  )
+
+  File.write("#{package_id}.zip", result.value) if result.success?
+end
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `SatMx.configure` | Configure certificate and private key |
+| `SatMx.configuration` | Get current configuration |
+| `SatMx.authenticate` | Get access token |
+| `SatMx.download_request` | Request CFDI download |
+| `SatMx.verify_request` | Check request status |
+| `SatMx.download_petition` | Download package |
+
+All methods return a `Result` object with:
+- `success?` - Boolean indicating success
+- `value` - Data on success, error hash `{:cod_estatus, :mensaje}` on failure
+- `xml` - Raw XML response
 
 ## 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 SatMx project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/sat_mx/blob/master/CODE_OF_CONDUCT.md).
+MIT

data/lib/sat_mx/authentication.rb

@@ -3,6 +3,7 @@ require "time"
 require "base64"
 
 module SatMx
+  # @api private
   class Authentication
     def self.authenticate(certificate:, private_key:, uuid: SecureRandom.uuid)
       new(
@@ -43,6 +44,7 @@ module SatMx
     attr_reader :xml_auth_body, :client
   end
 
+  # @api private
   class XmlAuthBody
     def initialize(certificate:, uuid:)
       @certificate = certificate

data/lib/sat_mx/body.rb

@@ -1,6 +1,7 @@
 require "base64"
 
 module SatMx
+  # @api private
   module Body
     S11 = "S11"
     XMLNS = "xmlns"

data/lib/sat_mx/client.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class Client
     HEADERS = {
       "content-type" => "text/xml; charset=utf-8",

data/lib/sat_mx/configuration.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   Configuration = Data.define(:certificate, :private_key) do
     def initialize(certificate:, private_key:, password:)
       super(

data/lib/sat_mx/download_petition.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class DownloadPetition
     def self.call(package_id:, requester_rfc:, access_token:, certificate:, private_key:)
       new(
@@ -41,8 +42,8 @@ module SatMx
             success?: false,
             xml: response.xml,
             value: {
-              CodEstatus: response_tag["CodEstatus"],
-              Mensaje: response_tag["Mensaje"]
+              cod_estatus: response_tag["CodEstatus"],
+              mensaje: response_tag["Mensaje"]
             }
           )
         end

data/lib/sat_mx/download_petition_body.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class DownloadPetitionBody
     include Body
 

data/lib/sat_mx/download_request.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class DownloadRequest
     def self.call(start_date:,
       end_date:,
@@ -56,8 +57,8 @@ module SatMx
         Result.new(
           success?: false,
           value: {
-            CodEstatus: download_result_tag.attr("CodEstatus").value,
-            Mensaje: download_result_tag.attr("Mensaje").value
+            cod_estatus: download_result_tag.attr("CodEstatus").value,
+            mensaje: download_result_tag.attr("Mensaje").value
           },
           xml:
         )

data/lib/sat_mx/download_request_body.rb

@@ -1,6 +1,7 @@
 require "time"
 
 module SatMx
+  # @api private
   class DownloadRequestBody
     include Body
 

data/lib/sat_mx/result.rb

@@ -1,3 +1,4 @@
 module SatMx
+  # @api private
   Result = Data.define(:success?, :value, :xml)
 end

data/lib/sat_mx/signer.rb

@@ -2,6 +2,7 @@ require "openssl"
 require "xmldsig"
 
 module SatMx
+  # @api private
   class Signer
     def self.sign(document:, private_key:)
       new(document:, private_key:).sign

data/lib/sat_mx/verify_request.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class VerifyRequest
     STATUS = {
       "1" => :accepted,
@@ -49,8 +50,8 @@ module SatMx
         Result.new(
           success?: false,
           value: {
-            CodEstatus: download_result_tag.attr("CodEstatus").value,
-            Mensaje: download_result_tag.attr("Mensaje").value
+            cod_status: download_result_tag.attr("CodEstatus").value,
+            mensaje: download_result_tag.attr("Mensaje").value
           },
           xml:
         )

data/lib/sat_mx/verify_request_body.rb

@@ -1,4 +1,5 @@
 module SatMx
+  # @api private
   class VerifyRequestBody
     include Body
 

data/lib/sat_mx/version.rb

@@ -1,3 +1,3 @@
 module SatMx
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/sat_mx.rb

@@ -46,6 +46,9 @@ module SatMx
     #     puts "Authentication failed"
     #   end
     #
+    # @param certificate [OpenSSL::X509::Certificate, nil] Certificate object (uses configuration if nil)
+    # @param private_key [OpenSSL::PKey::RSA, nil] Private key object (uses configuration if nil)
+    #
     # @return [SatMx::Result] A Result object containing:
     #   - success?: [Boolean] whether the authentication was successful
     #   - value: [String, nil] the authentication token if successful, nil otherwise
@@ -53,10 +56,139 @@ module SatMx
     #
     # @see SatMx::Authentication
     # @see SatMx::Result
-    def authenticate
+    def authenticate(certificate: nil, private_key: nil)
+      cert = certificate || configuration.certificate
+      key = private_key || configuration.private_key
       Authentication.authenticate(
-        certificate: configuration.certificate,
-        private_key: configuration.private_key
+        certificate: cert,
+        private_key: key
+      )
+    end
+
+    # Requests a download of CFDI documents from the SAT web service.
+    #
+    #   result = SatMx.download_request(
+    #     start_date: Time.new(2024, 1, 1),
+    #     end_date: Time.new(2024, 1, 31),
+    #     request_type: :cfdi,
+    #     issuing_rfc: "ABC010101ABC",
+    #     recipient_rfcs: ["XYZ020202XYZ"],
+    #     requester_rfc: "ABC010101ABC",
+    #     access_token: "your_access_token"
+    #   )
+    #   if result.success?
+    #     puts "Request ID: #{result.value}"
+    #   else
+    #     puts "Request failed: #{result.value}"
+    #   end
+    #
+    # @param start_date [Time] Start date for the search range
+    # @param end_date [Time] End date for the search range
+    # @param request_type [Symbol] Type of request (:cfdi or :retentions)
+    # @param issuing_rfc [String] RFC of the issuer
+    # @param recipient_rfcs [Array<String>] RFCs of the recipients
+    # @param requester_rfc [String] RFC of the requester
+    # @param access_token [String] Authentication token from SatMx.authenticate
+    # @param certificate [String, nil] Path to certificate file (uses configuration if nil)
+    # @param private_key [String, nil] Path to private key file (uses configuration if nil)
+    #
+    # @return [SatMx::Result] A Result object containing:
+    #   - success?: [Boolean] whether the request was successful
+    #   - value: [String, nil] the request ID if successful, or {cod_estatus:, mensaje:} on failure
+    #   - xml: [Nokogiri::XML::Document] the raw XML response from the service
+    #
+    # @see SatMx::DownloadRequest
+    # @see SatMx::Result
+    def download_request(start_date:, end_date:, request_type:, issuing_rfc:, recipient_rfcs:, requester_rfc:, access_token:, **options)
+      certificate = options[:certificate] || configuration.certificate
+      private_key = options[:private_key] || configuration.private_key
+      DownloadRequest.call(
+        start_date:,
+        end_date:,
+        request_type:,
+        issuing_rfc:,
+        recipient_rfcs:,
+        requester_rfc:,
+        access_token:,
+        certificate:,
+        private_key:
+      )
+    end
+
+    # Verifies the status of a previously submitted download request.
+    #
+    #   result = SatMx.verify_request(
+    #     request_id: "606c5667-345a-4630-8979-0769734ac80b",
+    #     requester_rfc: "ABC010101ABC",
+    #     access_token: "your_access_token"
+    #   )
+    #   if result.success?
+    #     puts "Status: #{result.value[:request_status]}"
+    #     puts "Packages: #{result.value[:package_ids]}"
+    #   else
+    #     puts "Verification failed: #{result.value}"
+    #   end
+    #
+    # @param request_id [String] The ID returned from SatMx.download_request
+    # @param requester_rfc [String] RFC of the requester
+    # @param access_token [String] Authentication token from SatMx.authenticate
+    # @param certificate [String, nil] Path to certificate file (uses configuration if nil)
+    # @param private_key [String, nil] Path to private key file (uses configuration if nil)
+    #
+    # @return [SatMx::Result] A Result object containing:
+    #   - success?: [Boolean] whether the verification was successful
+    #   - value: [Hash, nil] containing :request_status and :package_ids if successful, or {cod_estatus:, mensaje:} on failure
+    #   - xml: [Nokogiri::XML::Document] the raw XML response from the service
+    #
+    # @see SatMx::VerifyRequest
+    # @see SatMx::Result
+    def verify_request(request_id:, requester_rfc:, access_token:, **options)
+      certificate = options[:certificate] || configuration.certificate
+      private_key = options[:private_key] || configuration.private_key
+      VerifyRequest.call(
+        request_id:,
+        requester_rfc:,
+        access_token:,
+        certificate:,
+        private_key:
+      )
+    end
+
+    # Downloads a package of CFDI documents from the SAT web service.
+    #
+    #   result = SatMx.download_petition(
+    #     package_id: "18015570-C084-4BE8-BE36-476F5D46A133_01",
+    #     requester_rfc: "ABC010101ABC",
+    #     access_token: "your_access_token"
+    #   )
+    #   if result.success?
+    #     File.write("package.zip", result.value)
+    #   else
+    #     puts "Download failed: #{result.value}"
+    #   end
+    #
+    # @param package_id [String] The package ID from SatMx.verify_request
+    # @param requester_rfc [String] RFC of the requester
+    # @param access_token [String] Authentication token from SatMx.authenticate
+    # @param certificate [String, nil] Path to certificate file (uses configuration if nil)
+    # @param private_key [String, nil] Path to private key file (uses configuration if nil)
+    #
+    # @return [SatMx::Result] A Result object containing:
+    #   - success?: [Boolean] whether the download was successful
+    #   - value: [String, nil] Base64 encoded ZIP content if successful, or {cod_estatus:, mensaje:} on failure
+    #   - xml: [Nokogiri::XML::Document] the raw XML response from the service
+    #
+    # @see SatMx::DownloadPetition
+    # @see SatMx::Result
+    def download_petition(package_id:, requester_rfc:, access_token:, **options)
+      certificate = options[:certificate] || configuration.certificate
+      private_key = options[:private_key] || configuration.private_key
+      DownloadPetition.call(
+        package_id:,
+        requester_rfc:,
+        access_token:,
+        certificate:,
+        private_key:
       )
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sat_mx
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Oscar Rivas
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-17 00:00:00.000000000 Z
+date: 2026-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: xmldsig
@@ -143,7 +143,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/kadru/sat_mx
   changelog_uri: https://github.com/kadru/sat_mx/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -158,8 +158,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key: 
+rubygems_version: 3.5.11
+signing_key:
 specification_version: 4
 summary: a client to connect to SAT web services
 test_files: []