fulfil_api 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffd7b3a51a8fa0a8f76213567280c36f7c273115f46a6e397bbd3e8aefbc42df
-  data.tar.gz: 854ab5226509922e32fbccfdf7a2b49a7f8a2af25e313776a6a6d4284f4666c4
+  metadata.gz: 3cb2c76cac5e785167cc4edf3e1d2f92ab3ec3e330edd5e9a34ef50cf8d09705
+  data.tar.gz: ad349377c00dd1906553266232d0ce2bc4fd8f2aff7c96683c81dc1a9a3834de
 SHA512:
-  metadata.gz: 41e59d1b1d6a746d7fee0286d5af9290a6a38e474c45e3181a2a4ebca24ad5c7e65df00b6e84128763b5d753ba8a7e89bc7be0279de2c12c31c67298a866d610
-  data.tar.gz: d5598d3ae10daf60f75272cba43d185bb8a14cb8070297e9ab560bbca3758728dae40e9639d0bd6123f69cc17a9add6b61ac1a0d6d9113ea5fcd5c6cdf6ccdd4
+  metadata.gz: 16aea8d65692250edd1b51ce9089dec1b0d39ae850e9860d847f9e673a39b10b32e0b4a1c81ae29c8bcf7ece11f5fd10b0672896ebb0a89d815fb3ef3169aa6a
+  data.tar.gz: a825f694c375ed30e4fc76a9aef39a8adfc0298f0ad9fe99b749ba09e6dd54928d71de7a08e7c436a85f3855b8d88e637cc7e99d78f80842429e0c0d440d9cb4

data/lib/fulfil_api/report.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # The {FulfilApi::Report} class provides an interface for generating reports
+  # (e.g., PDF invoices) via Fulfil's report API. The API returns a temporary
+  # URL where the generated document can be downloaded.
+  #
+  # @example Generate and download an invoice PDF
+  #   report = FulfilApi::Report.generate("account.invoice.html", 3991)
+  #   report.url       # => "https://..."
+  #   report.filename  # => "Invoice.pdf"
+  #   report.mimetype  # => "application/pdf"
+  #
+  #   tempfile = report.download
+  #   tempfile.path    # => "/tmp/fulfil_report20260324-12345.pdf"
+  class Report
+    attr_reader :filename, :mimetype, :url
+
+    # Generates a report for the given record ID.
+    #
+    # @param report_name [String] The report identifier (e.g., "account.invoice.html").
+    # @param id [Integer] The record ID to generate the report for.
+    # @param data [Hash] Optional additional data for the report.
+    # @return [FulfilApi::Report] A report object with filename, mimetype, and url.
+    def self.generate(report_name, id, data: {})
+      response = FulfilApi.client.put("report/#{report_name}", body: { objects: [id], data: data })
+
+      new(
+        filename: response["filename"],
+        mimetype: response["mimetype"],
+        url: response["url"]
+      )
+    end
+
+    # @param filename [String] The filename of the generated report.
+    # @param mimetype [String] The MIME type of the generated report.
+    # @param url [String] The temporary URL to download the generated report.
+    def initialize(filename:, mimetype:, url:)
+      @filename = filename
+      @mimetype = mimetype
+      @url = url
+    end
+
+    # Downloads the report from the temporary URL and returns a {Tempfile}.
+    #
+    # The tempfile preserves the file extension from the report's filename
+    # (e.g., ".pdf") so it can be used directly with file upload APIs.
+    #
+    # @return [Tempfile] A tempfile containing the downloaded report.
+    def download
+      response = Faraday.get(url)
+
+      extension = File.extname(filename)
+      tempfile = Tempfile.new(["fulfil_report", extension])
+      tempfile.binmode
+      tempfile.write(response.body)
+      tempfile.rewind
+      tempfile
+    end
+  end
+end

data/lib/fulfil_api/test_helper.rb

@@ -65,6 +65,26 @@ module FulfilApi
         .and_return(status: status, body: response.to_json, headers: { "Content-Type": "application/json" })
     end
 
+    # Stubs an HTTP PUT request to the Fulfil report API based on the provided parameters.
+    #
+    # @param [Hash] response The response body to return as a JSON object (default is {}).
+    # @param [Integer] status The HTTP status code to return (default is 200).
+    # @param [Hash] options Additional options for the request URL.
+    # @option options [String] :report_name The report identifier
+    #   (e.g., 'account.invoice.html').
+    #
+    # @return [WebMock::RequestStub] The WebMock request stub object.
+    #
+    # @example Stub a report request for a specific report
+    #   stub_fulfil_report_request(report_name: "account.invoice.html", response: { url: "https://..." })
+    #
+    # @example Stub all report requests
+    #   stub_fulfil_report_request(response: { url: "https://..." })
+    def stub_fulfil_report_request(response: {}, status: 200, **options)
+      stubbed_report_request_for(**options)
+        .and_return(status: status, body: response.to_json, headers: { "Content-Type": "application/json" })
+    end
+
     private
 
     # Builds the WebMock request stub for the Fulfil 3PL API based on the provided method and options.
@@ -84,6 +104,22 @@ module FulfilApi
       end
     end
 
+    # Builds the WebMock request stub for the Fulfil report API based on the provided options.
+    #
+    # @param [Hash] options Additional options for the request URL.
+    # @option options [String] :report_name The report identifier
+    #   (e.g., 'account.invoice.html').
+    #
+    # @return [WebMock::RequestStub] The WebMock request stub object.
+    def stubbed_report_request_for(**options)
+      case options.transform_keys(&:to_sym)
+      in { report_name: }
+        stub_request(:put, %r{fulfil.io/api/v\d+/report/#{report_name}(.*)}i)
+      else
+        stub_request(:put, %r{fulfil.io/api/v\d+/report}i)
+      end
+    end
+
     # Builds the WebMock request stub for the Fulfil API based on the provided method and options.
     #
     # @param [String, Symbol] method The HTTP method to be stubbed (e.g., :get, :post).

data/lib/fulfil_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FulfilApi
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fulfil_api
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Stefan Vermaas
@@ -92,6 +92,7 @@ files:
 - lib/fulfil_api/relation/loadable.rb
 - lib/fulfil_api/relation/naming.rb
 - lib/fulfil_api/relation/query_methods.rb
+- lib/fulfil_api/report.rb
 - lib/fulfil_api/resource.rb
 - lib/fulfil_api/resource/attribute_assignable.rb
 - lib/fulfil_api/resource/attribute_type.rb