Feature: Support disposition attachment

lib/fileboost/helpers.rb

@@ -5,7 +5,7 @@ module Helpers
     # Generate an optimized image tag using Fileboost
     #
     # @param asset [ActiveStorage::Blob, ActiveStorage::Attached, ActiveStorage::VariantWithRecord] The ActiveStorage image asset
-    # @param options [Hash] Image transformation and HTML options
+    # @param options [Hash] Accepts a `:resize` hash for transformations plus standard HTML options
     # @return [String] HTML image tag
     #
     # Examples:
@@ -25,7 +25,7 @@ def fileboost_image_tag(asset, **options)
     # Generate an optimized URL using Fileboost
     #
     # @param asset [ActiveStorage::Blob, ActiveStorage::Attached, ActiveStorage::VariantWithRecord] The ActiveStorage image asset
-    # @param options [Hash] Image transformation options
+    # @param options [Hash] Supports a `:resize` hash for image transformations and an optional `:disposition`
     # @return [String, nil] The optimized URL or nil if generation failed
     #
     # Examples:

lib/fileboost/url_builder.rb

@@ -45,16 +45,20 @@ def self.build_url(asset, **options)
       # Extract and normalize transformation parameters
       transformation_params = extract_transformation_params(asset, options)
 
-      # Generate HMAC signature for secure authentication
+      # Separate disposition from transformation params for signature generation
+      disposition = transformation_params.delete("disposition")
+
+      # Generate HMAC signature for secure authentication (excluding disposition)
       signature = Fileboost::SignatureGenerator.generate(
         asset_path: asset_path,
         params: transformation_params
       )
 
       raise SignatureGenerationError, "Failed to generate signature" unless signature
 
-      # Add signature to parameters
+      # Add signature and disposition back to final URL parameters
       all_params = transformation_params.merge("sig" => signature)
+      all_params["disposition"] = disposition if disposition
 
       # Build final URL
       uri = URI.join(base_url, full_path)
@@ -118,6 +122,11 @@ def self.extract_transformation_params(asset, options)
         end
       end
 
+      disposition = options[:disposition] || options["disposition"]
+      if disposition.present?
+        params["disposition"] = disposition.to_s.strip.downcase
+      end
+
       params
     end
 

spec/fileboost/helpers_spec.rb

@@ -60,6 +60,12 @@
       expect(url).to include("fit=scale-down")
     end
 
+    it "includes disposition parameter when provided" do
+      url = fileboost_url_for(blob, disposition: :attachment)
+
+      expect(url).to include("disposition=attachment")
+    end
+
     it "raises ArgumentError for invalid asset type" do
       expect {
         fileboost_url_for("invalid", resize: { w: 300 })

spec/fileboost/url_builder_spec.rb

@@ -150,5 +150,24 @@
         expect(url).to include("fit=scale-down")
       end
     end
+
+    context "with disposition parameter" do
+      it "includes disposition in URL but excludes from signature generation" do
+        # Generate URLs with and without disposition
+        url_without_disposition = Fileboost::UrlBuilder.build_url(blob, resize: { w: 300 })
+        url_with_disposition = Fileboost::UrlBuilder.build_url(blob, resize: { w: 300 }, disposition: "attachment")
+
+        # Extract signatures from both URLs
+        sig_without = URI.decode_www_form(URI.parse(url_without_disposition).query).to_h["sig"]
+        sig_with = URI.decode_www_form(URI.parse(url_with_disposition).query).to_h["sig"]
+
+        # Signatures should be identical (disposition not affecting signature)
+        expect(sig_without).to eq(sig_with)
+
+        # But the URL with disposition should include the disposition parameter
+        expect(url_with_disposition).to include("disposition=attachment")
+        expect(url_without_disposition).not_to include("disposition=")
+      end
+    end
   end
 end