Simplify apps API contract

mconnell · mconnell · commit 4eb3844d2499 · 2026-03-31T16:07:53.000+01:00
diff --git a/.rubocop.yml b/.rubocop.yml
@@ -12,3 +12,6 @@ Style/Documentation:
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
+
+Style/SymbolArray:
+  EnforcedStyle: brackets
diff --git a/README.md b/README.md
@@ -39,18 +39,23 @@ List available apps:
 
 ```ruby
 apps = PreflightQA::Apps.list
-apps.first.name
+apps["apple_mail_mac"]["name"]
+apps["apple_mail_mac"]["modes"]
 ```
 
 Create a screenshot submission:
 
 ```ruby
+apps = PreflightQA::Apps.list
+
 submission = PreflightQA::Screenshots.create(
   subject: "My Test Email",
   html: "<html><body>Hello world</body></html>",
-  apps: ["apple_mail", "outlook_mac"],
-  webhook_url: "https://example.com/preflight/webhook",
-  mode: "dark"
+  apps: {
+    apple_mail_mac: [:light, :dark],
+    outlook_mac: [:light]
+  },
+  webhook_url: "https://example.com/preflight/webhook"
 )
 
 submission.uuid
@@ -67,7 +72,7 @@ screenshots.each do |screenshot|
 end
 ```
 
-`PreflightQA::Apps.list` returns `Array<PreflightQA::App>`.
+`PreflightQA::Apps.list` returns the raw `data["apps"]` hash from the API.
 
 `PreflightQA::Screenshots.create` returns `PreflightQA::Submission`.
 
diff --git a/Rakefile b/Rakefile
@@ -9,4 +9,4 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+task default: [:spec, :rubocop]
diff --git a/lib/preflight_qa.rb b/lib/preflight_qa.rb
@@ -4,7 +4,6 @@
 require_relative "preflight_qa/configuration"
 require_relative "preflight_qa/errors"
 require_relative "preflight_qa/client"
-require_relative "preflight_qa/app"
 require_relative "preflight_qa/submission"
 require_relative "preflight_qa/screenshot"
 require_relative "preflight_qa/apps"
diff --git a/lib/preflight_qa/app.rb b/lib/preflight_qa/app.rb
diff --git a/lib/preflight_qa/apps.rb b/lib/preflight_qa/apps.rb
@@ -7,7 +7,7 @@ module Apps
 
     def list
       payload = PreflightQA.client.get("/apps")
-      apps_from(payload).map { |slug, app| App.from_payload(slug, app) }
+      apps_from(payload)
     end
 
     def apps_from(payload)
diff --git a/lib/preflight_qa/screenshots.rb b/lib/preflight_qa/screenshots.rb
@@ -38,17 +38,30 @@ def build_create_payload(subject:, html:, options:)
       payload = { subject: subject, html: html }
       append_optional_field(payload, :apps, options)
       append_optional_field(payload, :webhook_url, options)
-      append_optional_field(payload, :mode, options)
-      payload.merge(options.except(:apps, :webhook_url, :mode))
+      payload.merge(options.except(:apps, :webhook_url))
     end
     private_class_method :build_create_payload
 
     def append_optional_field(payload, key, options)
       return unless options.key?(key)
       return if options[key].nil?
 
-      payload[key] = options[key]
+      payload[key] = key == :apps ? normalize_apps(options[key]) : options[key]
     end
     private_class_method :append_optional_field
+
+    def normalize_apps(apps)
+      raise ArgumentError, "apps must be a hash of app keys to mode arrays" unless apps.is_a?(Hash)
+
+      apps.each_with_object({}) do |(app, modes), normalized|
+        normalized[app.to_s] = normalize_modes(modes)
+      end
+    end
+    private_class_method :normalize_apps
+
+    def normalize_modes(modes)
+      Array(modes).map(&:to_s)
+    end
+    private_class_method :normalize_modes
   end
 end
diff --git a/spec/preflight_qa/apps_spec.rb b/spec/preflight_qa/apps_spec.rb
@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 RSpec.describe PreflightQA::Apps do
-  it "returns typed app objects" do
+  it "returns the raw app hash" do
     client = instance_double(PreflightQA::Client)
     allow(PreflightQA).to receive(:client).and_return(client)
     allow(client).to receive(:get).with("/apps").and_return(
@@ -20,17 +20,18 @@
     result = described_class.list
 
     expect(result).to eq(
-      [
-        PreflightQA::App.new(
-          app: "apple_mail_mac",
-          name: "Apple Mail (Mac)",
-          modes: %w[light dark],
-          raw: {
-            "name" => "Apple Mail (Mac)",
-            "modes" => %w[light dark]
-          }
-        )
-      ]
+      {
+        "apple_mail_mac" => {
+          "name" => "Apple Mail (Mac)",
+          "modes" => %w[light dark]
+        }
+      }
+    )
+    expect(result["apple_mail_mac"]).to eq(
+      {
+        "name" => "Apple Mail (Mac)",
+        "modes" => %w[light dark]
+      }
     )
   end
 end
diff --git a/spec/preflight_qa/screenshots_spec.rb b/spec/preflight_qa/screenshots_spec.rb
@@ -45,19 +45,17 @@
       body: {
         subject: "My Test Email",
         html: "<html>test</html>",
-        apps: ["apple_mail"],
+        apps: { "apple_mail_mac" => %w[light dark] },
         webhook_url: "https://example.test/webhook",
-        mode: "dark",
         locale: "en-GB"
       }
     ).and_return(submission_payload)
 
     result = described_class.create(
       subject: "My Test Email",
       html: "<html>test</html>",
-      apps: ["apple_mail"],
+      apps: { apple_mail_mac: [:light, :dark] },
       webhook_url: "https://example.test/webhook",
-      mode: "dark",
       locale: "en-GB"
     )
 
@@ -71,6 +69,16 @@
     )
   end
 
+  it "raises when apps is not a hash" do
+    expect do
+      described_class.create(
+        subject: "My Test Email",
+        html: "<html>test</html>",
+        apps: ["apple_mail_mac"]
+      )
+    end.to raise_error(ArgumentError, /apps must be a hash/)
+  end
+
   it "finds screenshots by uuid" do
     allow(client).to receive(:get)
       .with("/screenshots/1b153496-f702-4f89-85b4-cd1a9516cbbe")

Original file line number	Diff line number	Diff line change
`@@ -9,4 +9,4 @@ require "rubocop/rake_task"`
`9`	`9`
`10`	`10`	`RuboCop::RakeTask.new`
`11`	`11`
`12`		`-task default: %i[spec rubocop]`
	`12`	`+task default: [:spec, :rubocop]`