portage-cli 0.10.0 → 0.12.0

data/lib/portage/cli/index/database.rb

@@ -0,0 +1,150 @@
+require "json"
+require "fileutils"
+require "sqlite3"
+require_relative "schema"
+require_relative "legacy_import"
+
+module Portage
+  module Cli
+    module Index
+      # `~/.portage/index/index.sqlite3` — the one file behind Index::Store
+      # and Index::ProductStore (docs/plans/local-catalogue.md Phase 1).
+      # Plain SQL over the `sqlite3` gem, no ORM: every entry is stored as
+      # the same JSON object the old stores.json/products.json held, so the
+      # entry shapes documented on Store/ProductStore did not change.
+      #
+      # Posture: the file is created 0600 (and so are SQLite's -wal/-shm
+      # side files, which copy the main file's mode); it runs in WAL mode
+      # with a busy timeout; a failed write raises rather than being
+      # swallowed. Nothing is created until something is written — a read
+      # of an index that doesn't exist yet just comes back empty.
+      #
+      # Forward-only schema: MIGRATIONS[n] takes user_version n to n + 1,
+      # and a database stamped newer than this build knows is refused
+      # rather than guessed at.
+      #
+      # The open that creates the database also imports a legacy stores.json/
+      # products.json that sits beside it, in one transaction, then renames
+      # it to *.json.migrated. Only that one open does — later opens never
+      # look, even if the tables have since been emptied — and nothing is
+      # ever deleted.
+      class Database
+        class Error < StandardError; end
+
+        FILENAME = "index.sqlite3".freeze
+        BUSY_TIMEOUT_MS = 5_000
+
+        # table => its key column. The legacy json file for a table is
+        # "<table>.json".
+        TABLES = { "stores" => "origin", "products" => "key" }.freeze
+
+        # The database that lives beside a legacy stores.json/products.json.
+        def self.path_for(json_path) = File.join(File.dirname(json_path), FILENAME)
+
+        attr_reader :path
+
+        def initialize(path:)
+          @path = path
+        end
+
+        # True once there is something to read: the database itself, or a
+        # legacy json file that the next open will import.
+        def exists? = File.exist?(@path) || LegacyImport.files(File.dirname(@path)).any?
+
+        # @return [Hash] key => parsed entry, in insertion order.
+        def entries(table)
+          return {} unless exists?
+
+          execute("SELECT #{TABLES.fetch(table)}, data FROM #{table} ORDER BY rowid").to_h { |k, d| [k, JSON.parse(d)] }
+        end
+
+        def get(table, key)
+          return nil unless exists?
+
+          row = execute("SELECT data FROM #{table} WHERE #{TABLES.fetch(table)} = ?", [key]).first
+          row && JSON.parse(row.first)
+        end
+
+        def put(table, key, entry)
+          column = TABLES.fetch(table)
+          execute("INSERT INTO #{table} (#{column}, data) VALUES (?, ?) " \
+                  "ON CONFLICT(#{column}) DO UPDATE SET data = excluded.data", [key, JSON.generate(entry)])
+        end
+
+        def delete(table, key)
+          execute("DELETE FROM #{table} WHERE #{TABLES.fetch(table)} = ?", [key])
+        end
+
+        def count(table)
+          return 0 unless exists?
+
+          execute("SELECT COUNT(*) FROM #{table}").first.first
+        end
+
+        # Reentrant: a nested call joins the outer transaction. IMMEDIATE
+        # takes the write lock up front, so a read-modify-write inside it
+        # can't interleave with another process's.
+        def transaction(&)
+          return yield if connection.transaction_active?
+
+          connection.transaction(:immediate, &)
+        end
+
+        # @return [Array<Array>] raw rows — for the specs and Phase 2's
+        #   search; everything else goes through the entry methods above.
+        def execute(sql, binds = [])
+          connection.execute(sql, binds)
+        end
+
+        def pragma(name) = execute("PRAGMA #{name}").flatten.first
+
+        # What `portage doctor` reports.
+        def info
+          stores = count("stores")
+          products = count("products")
+          { path: @path, exists: File.exist?(@path), stores: stores, products: products,
+            fts5: Schema.fts5_available? }
+        end
+
+        private
+
+        def connection
+          @connection ||= open_connection
+        end
+
+        def open_connection
+          FileUtils.mkdir_p(File.dirname(@path))
+          File.open(@path, File::CREAT | File::WRONLY, 0o600) { nil }
+          FileUtils.chmod(0o600, @path)
+          db = SQLite3::Database.new(@path)
+          db.busy_timeout = BUSY_TIMEOUT_MS
+          db.execute("PRAGMA journal_mode = WAL")
+          db.execute("PRAGMA synchronous = NORMAL")
+          @connection = db
+          # One transaction, so a failed import leaves the database unstamped
+          # and the next open tries again rather than skipping the import.
+          transaction { LegacyImport.new(self, File.dirname(@path)).call if migrate.zero? }
+          db
+        rescue StandardError
+          @connection&.close
+          @connection = nil
+          raise
+        end
+
+        def migrate
+          version = @connection.get_first_value("PRAGMA user_version")
+          if version > Schema::MIGRATIONS.length
+            raise Error,
+                  "#{@path} is schema v#{version}, newer than this portage understands"
+          end
+
+          Schema::MIGRATIONS.drop(version).each_with_index do |step, i|
+            step.call(@connection)
+            @connection.execute("PRAGMA user_version = #{version + i + 1}")
+          end
+          version
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/index/entry_product.rb

@@ -0,0 +1,37 @@
+require "portage/ucp"
+
+module Portage
+  module Cli
+    module Index
+      # A ProductStore entry as the persisted subset of a UCP Product wire
+      # hash (docs/plans/local-catalogue.md Phase 3), for `index search`'s
+      # `product` field. Built only from what the index keeps, so it has no
+      # id, description, price_range or availability: the index never stores
+      # a price or stock, and a missing field is left out rather than faked.
+      # The live Product comes from `find`.
+      module EntryProduct
+        TAXONOMY = "google_product_category".freeze
+
+        module_function
+
+        # @param entry [Hash] a ProductStore entry.
+        # @return [Hash] string-keyed, UCP Product shaped.
+        def wire(entry)
+          wire = { "title" => entry["title"], "handle" => entry["handle"], "url" => entry["url"],
+                   "media" => media(entry["image_url"]), "options" => entry["options"],
+                   "variants" => Array(entry["variant_ids"]).map { |id| { "id" => id } },
+                   "categories" => category(entry["category"]) }
+          wire.reject { |_field, value| value.nil? || value == [] }
+        end
+
+        def media(url)
+          url.to_s.empty? ? nil : [Portage::Ucp::Media.new(type: "image", url: url).to_wire_h]
+        end
+
+        def category(id)
+          id.to_s.empty? ? nil : [Portage::Ucp::Category.new(value: id, taxonomy: TAXONOMY).to_wire_h]
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/index/legacy_import.rb

@@ -0,0 +1,54 @@
+require "json"
+
+module Portage
+  module Cli
+    module Index
+      # Moves a pre-SQLite stores.json/products.json into an Index::Database
+      # (docs/plans/local-catalogue.md Phase 1): every object entry, in one
+      # transaction, then the file is renamed to *.json.migrated. Nothing
+      # is ever deleted, and an unreadable or non-object file is left
+      # untouched. Index::Database runs this only on the open that creates
+      # the database, so it happens at most once.
+      class LegacyImport
+        # @return [Array<String>] the legacy json files present in `dir`.
+        def self.files(dir)
+          Database::TABLES.keys.map { |table| File.join(dir, "#{table}.json") }.select { |file| File.file?(file) }
+        end
+
+        def initialize(database, dir)
+          @database = database
+          @dir = dir
+        end
+
+        def call
+          self.class.files(@dir).each do |file|
+            entries = read(file)
+            next unless entries
+
+            @database.transaction do
+              entries.each { |key, entry| @database.put(File.basename(file, ".json"), key, entry) if entry.is_a?(Hash) }
+            end
+            rename(file)
+          end
+        end
+
+        private
+
+        def read(file)
+          parsed = JSON.parse(File.read(file, encoding: "UTF-8"))
+          parsed.is_a?(Hash) ? parsed : nil
+        rescue JSON::ParserError, SystemCallError
+          nil
+        end
+
+        # The rows are already committed, so a rename that fails must not
+        # fail the open — the file is just left where it was.
+        def rename(file)
+          File.rename(file, "#{file}.migrated")
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/index/product_store.rb

@@ -1,10 +1,12 @@
 require "json"
-require "fileutils"
+require_relative "database"
+require_relative "search"
 
 module Portage
   module Cli
     module Index
-      # `~/.portage/index/products.json` — product identities the index has
+      # The `products` table of `~/.portage/index/index.sqlite3` (Index::Database;
+      # `products.json` before docs/plans/local-catalogue.md Phase 1) — product identities the index has
       # seen, one entry per GTIN/MPN (when a source gives one) or per
       # title+brand otherwise. **No prices or stock** — those are always
       # live, read straight from the store's own catalog at buy time
@@ -19,33 +21,92 @@ module Portage
       class ProductStore
         PATH = File.join(Dir.home, ".portage", "index", "products.json").freeze
 
+        # @param path [String] where the legacy products.json lives (or
+        #   would live) — the database sits beside it, and a products.json
+        #   found there is imported on first open.
         def initialize(path: PATH)
-          @path = path
+          @db = Database.new(path: Database.path_for(path))
         end
 
-        def all = entries.values
+        def all = @db.entries("products").values
 
-        def find(key) = entries[key]
+        def find(key) = @db.get("products", key)
 
         # @param key [String] a stable key for this product — the source's
         #   GTIN/MPN when it has one, else a normalized title+brand.
         # @param origin [String] the store this sighting came from.
         # @param seen_at [Integer] unix seconds.
         def upsert(key, origin:, seen_at:, **fields)
-          existing = entries[key] || { "key" => key, "aliases" => [], "stores" => [] }
+          @db.transaction { merge_and_write(key, origin, seen_at, fields) }
+        end
+
+        # A batch of sightings in one transaction — all of them land or,
+        # if any raises, none do. Each row is a Hash: `key:`, `origin:`,
+        # `seen_at:` plus the same fields #upsert takes. Rows merge in
+        # order, so a key repeated in one batch accumulates like two
+        # #upsert calls would.
+        # @return [Array<Hash>] the merged entries, in row order.
+        def upsert_many(rows)
+          return [] if rows.empty?
+
+          @db.transaction do
+            rows.map do |row|
+              fields = row.except(:key, :origin, :seen_at)
+              merge_and_write(row.fetch(:key), row.fetch(:origin), row.fetch(:seen_at), fields)
+            end
+          end
+        end
+
+        def exists? = @db.exists?
+
+        def count = @db.count("products")
+
+        # `index show --products`: one page of entries, in insertion order.
+        def page(number, per_page:)
+          return [] unless exists?
+
+          offset = ([number.to_i, 1].max - 1) * per_page
+          rows = @db.execute("SELECT data FROM products ORDER BY id LIMIT ? OFFSET ?", [per_page, offset])
+          rows.map { |(data)| JSON.parse(data) }
+        end
+
+        # `portage index search` (docs/plans/local-catalogue.md Phase 2):
+        # every query word must match title, brand, category or an alias
+        # (as a prefix, after dropping a plural ending), best bm25 first.
+        # Without FTS5 (a system SQLite built without it) the same filters
+        # run as a LIKE scan, unranked. Untrusted seeds, same as every
+        # other entry: no price, no stock.
+        # @param store [String, nil] a host or URL; matches that host's origin.
+        # @return [Array<Hash>] entries.
+        def search(query, category: nil, store: nil, limit: 20)
+          words = Search.words(query)
+          return [] if words.empty? || !exists?
+
+          sql, binds = Search.sql(words, category: category, host: Search.host_of(store), limit: limit,
+                                         fts: search_engine == "fts5")
+          @db.execute(sql, binds).map { |(data)| JSON.parse(data) }
+        end
+
+        # "fts5", or "like" when the database has no products_fts table.
+        def search_engine
+          return Schema.fts5_available? ? "fts5" : "like" unless exists?
+
+          fts = @db.execute("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'products_fts'")
+          fts.empty? ? "like" : "fts5"
+        end
+
+        private
+
+        def merge_and_write(key, origin, seen_at, fields)
+          existing = @db.get("products", key) || { "key" => key, "aliases" => [], "stores" => [] }
           aliases = merge_aliases(existing, fields[:title])
           merged = existing.merge(fields.transform_keys(&:to_s)) { |field, old, new| merge_field(field, old, new) }
           merged["aliases"] = aliases
           merged["stores"] = merge_stores(merged["stores"], origin, seen_at)
-          entries[key] = merged
-          write
+          @db.put("products", key, merged)
           merged
         end
 
-        def exists? = File.exist?(@path)
-
-        private
-
         # `aliases`/`stores` accumulate across upserts (merged separately
         # below), `sources` is the union of every sighting's; every other
         # field (title, brand, gtin, category) is just the latest
@@ -72,29 +133,6 @@ module Portage
           kept = Array(stores).reject { |s| s["origin"] == origin }
           (kept + [{ "origin" => origin, "last_seen" => seen_at }]).sort_by { |s| s["origin"] }
         end
-
-        def entries
-          @entries ||= read
-        end
-
-        def read
-          return {} unless File.readable?(@path)
-
-          # See Index::Store#read's comment — a product title routinely
-          # carries non-ASCII bytes, so this has to read as UTF-8 rather
-          # than whatever the process's default external encoding is.
-          parsed = JSON.parse(File.read(@path, encoding: "UTF-8"))
-          parsed.is_a?(Hash) ? parsed : {}
-        rescue StandardError
-          {}
-        end
-
-        def write
-          FileUtils.mkdir_p(File.dirname(@path))
-          File.write(@path, JSON.generate(@entries))
-        rescue StandardError
-          nil
-        end
       end
     end
   end

data/lib/portage/cli/index/schema.rb

@@ -0,0 +1,70 @@
+require "sqlite3"
+
+module Portage
+  module Cli
+    module Index
+      # The SQL behind Index::Database, forward-only: MIGRATIONS[n] takes
+      # user_version n to n + 1.
+      module Schema
+        # Kept minimal: `data` is the entry's JSON verbatim. `products`
+        # carries an integer id (rather than the key alone being the
+        # primary key) only so products_fts can share its rowid, which
+        # stays stable across VACUUM.
+        SCHEMA = <<~SQL.freeze
+          CREATE TABLE stores (origin TEXT PRIMARY KEY, data TEXT NOT NULL);
+          CREATE TABLE products (id INTEGER PRIMARY KEY, key TEXT NOT NULL UNIQUE, data TEXT NOT NULL);
+          CREATE TABLE product_stores (key TEXT NOT NULL, origin TEXT NOT NULL, last_seen INTEGER,
+                                       PRIMARY KEY (key, origin));
+          CREATE TRIGGER products_stores_ins AFTER INSERT ON products BEGIN
+            INSERT OR REPLACE INTO product_stores (key, origin, last_seen)
+              SELECT new.key, json_extract(value, '$.origin'), json_extract(value, '$.last_seen')
+              FROM json_each(new.data, '$.stores');
+          END;
+          CREATE TRIGGER products_stores_upd AFTER UPDATE OF data ON products BEGIN
+            DELETE FROM product_stores WHERE key = old.key;
+            INSERT OR REPLACE INTO product_stores (key, origin, last_seen)
+              SELECT new.key, json_extract(value, '$.origin'), json_extract(value, '$.last_seen')
+              FROM json_each(new.data, '$.stores');
+          END;
+        SQL
+
+        # Needs FTS5 compiled in, which the gem's bundled SQLite has and a
+        # system-libraries build might not — see fts5_available?.
+        FTS_SCHEMA = <<~SQL.freeze
+          CREATE VIRTUAL TABLE products_fts USING fts5(key UNINDEXED, title, brand, category, aliases);
+          CREATE TRIGGER products_fts_ins AFTER INSERT ON products BEGIN
+            INSERT INTO products_fts (rowid, key, title, brand, category, aliases)
+              VALUES (new.id, new.key, json_extract(new.data, '$.title'), json_extract(new.data, '$.brand'),
+                      json_extract(new.data, '$.category'),
+                      (SELECT group_concat(value, ' ') FROM json_each(new.data, '$.aliases')));
+          END;
+          CREATE TRIGGER products_fts_upd AFTER UPDATE OF data ON products BEGIN
+            DELETE FROM products_fts WHERE rowid = old.id;
+            INSERT INTO products_fts (rowid, key, title, brand, category, aliases)
+              VALUES (new.id, new.key, json_extract(new.data, '$.title'), json_extract(new.data, '$.brand'),
+                      json_extract(new.data, '$.category'),
+                      (SELECT group_concat(value, ' ') FROM json_each(new.data, '$.aliases')));
+          END;
+          CREATE TRIGGER products_fts_del AFTER DELETE ON products BEGIN
+            DELETE FROM products_fts WHERE rowid = old.id;
+          END;
+        SQL
+
+        # Each entry is a script run at that user_version. The FTS one is a
+        # no-op on a build without FTS5 (its version still advances).
+        MIGRATIONS = [
+          ->(db) { db.execute_batch(SCHEMA) },
+          ->(db) { db.execute_batch(FTS_SCHEMA) if Schema.fts5_available? }
+        ].freeze
+
+        # @return [Boolean] whether the linked SQLite was built with FTS5.
+        def self.fts5_available?
+          db = SQLite3::Database.new(":memory:")
+          db.execute("PRAGMA compile_options").flatten.include?("ENABLE_FTS5")
+        ensure
+          db&.close
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/index/search.rb

@@ -0,0 +1,73 @@
+require "uri"
+
+module Portage
+  module Cli
+    module Index
+      # The SQL behind ProductStore#search: an FTS5 MATCH over products_fts
+      # (Index::Schema) ranked by bm25, or the same filters as a LIKE scan
+      # when the database has no FTS table.
+      module Search
+        # bm25 weights for products_fts's columns: key (unindexed), title,
+        # brand, category, aliases. A title hit outranks a brand-only one.
+        BM25 = "bm25(products_fts, 0.0, 10.0, 3.0, 1.0, 5.0)".freeze
+        LIKE_COLUMNS = %w[$.title $.brand $.category $.aliases].freeze
+        HOST_LIKE = Array.new(4) { "s.origin LIKE ?" }.join(" OR ").freeze
+
+        module_function
+
+        # Letters and digits only, so nothing the user types is FTS5 syntax.
+        # A trailing plural ending is dropped and each word matched as a
+        # prefix, so "lights" finds "Light" and "Lighting".
+        def words(query)
+          query.to_s.downcase.scan(/\p{Alnum}+/).map { |w| w.length > 3 ? w.sub(/(?:ies|es|s)\z/, "") : w }
+        end
+
+        def host_of(store)
+          return nil if store.to_s.strip.empty?
+
+          text = store.to_s.strip
+          (text.include?("://") ? URI.parse(text).host : text.split(%r{[/?]}).first).to_s.downcase
+        rescue URI::InvalidURIError
+          text.downcase
+        end
+
+        # @return [Array(String, Array)] sql and binds.
+        def sql(words, category:, host:, limit:, fts:)
+          match_sql, binds = fts ? fts_match(words) : like_match(words)
+          filters = [match_sql]
+          if category
+            filters << "json_extract(p.data, '$.category') = ?"
+            binds << category.to_s
+          end
+          if host
+            filters << "EXISTS (SELECT 1 FROM product_stores s WHERE s.key = p.key AND (#{HOST_LIKE}))"
+            binds.concat(host_patterns(host))
+          end
+          [select(fts, filters.join(" AND ")), binds + [limit.to_i]]
+        end
+
+        # The host itself or any subdomain of it, with or without a port —
+        # so `--store jbhifi.com.au` finds https://www.jbhifi.com.au.
+        def host_patterns(host) = ["%://#{host}", "%://#{host}:%", "%.#{host}", "%.#{host}:%"]
+
+        def select(fts, where)
+          if fts
+            "SELECT p.data FROM products_fts JOIN products p ON p.id = products_fts.rowid " \
+              "WHERE #{where} ORDER BY #{BM25} LIMIT ?"
+          else
+            "SELECT p.data FROM products p WHERE #{where} ORDER BY p.id LIMIT ?"
+          end
+        end
+
+        def fts_match(words)
+          ["products_fts MATCH ?", [words.map { |w| %("#{w}"*) }.join(" ")]]
+        end
+
+        def like_match(words)
+          any_column = LIKE_COLUMNS.map { |path| "lower(json_extract(p.data, '#{path}')) LIKE ?" }.join(" OR ")
+          [words.map { "(#{any_column})" }.join(" AND "), words.flat_map { |w| ["%#{w}%"] * LIKE_COLUMNS.length }]
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/index/sources/storefront_products/mapper.rb

@@ -0,0 +1,127 @@
+require "portage/ucp"
+
+require_relative "../../../classifier"
+
+module Portage
+  module Cli
+    module Index
+      module Sources
+        class StorefrontProducts
+          # One Shopify `/products.json` product -> Portage::Ucp::Product
+          # (docs/plans/local-catalogue.md Phase 2), then the index sighting
+          # taken from that Product. The product shape is UCP's, never a
+          # parallel "card" vocabulary.
+          #
+          # Not portage-ucp-shopify's Mapper: that one reads Storefront
+          # GraphQL nodes (camelCase, gids, MoneyV2 with a currency), not the
+          # REST products.json shape, and portage-cli doesn't depend on that
+          # gem.
+          #
+          # The Product carries what the store sent, price and availability
+          # included (products.json has no currency, so Price#currency is
+          # nil). #sighting is what the index persists, and it takes only
+          # identity fields from the Product: price and availability never
+          # reach it.
+          module Mapper
+            MAX_CATEGORIES = 3
+            TAXONOMY = "google_product_category".freeze
+            # Shopify's own placeholder for a product with no real options.
+            PLACEHOLDER_OPTION = { "name" => "Title", "values" => ["Default Title"] }.freeze
+
+            module_function
+
+            # @param raw [Hash] one entry of products.json's "products".
+            # @param classify [#call] text -> category ids (Classifier).
+            def product(raw, origin:, classify: Classifier.method(:categories_for))
+              options = product_options(raw)
+              Portage::Ucp::Product.new(
+                id: "gid://shopify/Product/#{raw['id']}", title: raw["title"].to_s,
+                description: Portage::Ucp::Description.new(html: raw["body_html"]),
+                price_range: price_range(raw), variants: Array(raw["variants"]).map { |v| variant(v, options) },
+                handle: raw["handle"], url: "#{origin}/products/#{raw['handle']}",
+                categories: categories(raw, classify), media: Array(raw["images"]).map { |i| media(i) },
+                options: options.map { |o| option(o) }, tags: Array(raw["tags"])
+              )
+            end
+
+            # @return [Hash] an Index::Builder sighting: the ProductStore
+            #   fields plus `product:`, the extra entry fields this source
+            #   adds (handle, url, image_url, options, variant_ids).
+            def sighting(raw, origin:, classify: Classifier.method(:categories_for))
+              product = product(raw, origin: origin, classify: classify)
+              { origin: origin, url: product.url, title: product.title, brand: brand(raw), gtin: nil,
+                categories: product.categories.select { |c| c.taxonomy == TAXONOMY }.map(&:value),
+                product: { handle: product.handle, url: product.url, image_url: product.media.first&.url,
+                           options: product.options.map(&:to_wire_h), variant_ids: product.variants.map(&:id) } }
+            end
+
+            def brand(raw)
+              vendor = raw["vendor"].to_s.strip
+              vendor.empty? ? nil : vendor
+            end
+
+            def product_options(raw)
+              Array(raw["options"]).reject { |o| o.slice("name", "values") == PLACEHOLDER_OPTION }
+            end
+
+            def option(raw)
+              values = Array(raw["values"]).map { |label| Portage::Ucp::OptionValue.new(label: label.to_s) }
+              Portage::Ucp::ProductOption.new(name: raw["name"].to_s, values: values)
+            end
+
+            def variant(raw, options)
+              Portage::Ucp::Variant.new(
+                id: "gid://shopify/ProductVariant/#{raw['id']}", title: raw["title"].to_s,
+                description: Portage::Ucp::Description.new(plain: raw["title"].to_s), price: price(raw["price"]),
+                sku: raw["sku"].to_s.empty? ? nil : raw["sku"],
+                list_price: raw["compare_at_price"] ? price(raw["compare_at_price"]) : nil,
+                availability: raw.key?("available") ? { "available" => raw["available"] } : nil,
+                options: selected_options(raw, options), media: variant_media(raw)
+              )
+            end
+
+            # option1..option3 line up with the product's options by
+            # position; the placeholder option is already gone, so a
+            # "Default Title" variant selects nothing.
+            def selected_options(raw, options)
+              options.each_with_index.filter_map do |opt, i|
+                label = raw["option#{i + 1}"]
+                Portage::Ucp::SelectedOption.new(name: opt["name"].to_s, label: label.to_s) if label
+              end
+            end
+
+            def variant_media(raw) = raw["featured_image"] ? [media(raw["featured_image"])] : []
+
+            def media(raw)
+              Portage::Ucp::Media.new(type: "image", url: raw["src"], alt_text: raw["alt"], width: raw["width"],
+                                      height: raw["height"])
+            end
+
+            def price(amount)
+              Portage::Ucp::Price.new(amount: Portage::Ucp::Support::Amounts.decimal_to_minor(amount), currency: nil)
+            end
+
+            def price_range(raw)
+              amounts = Array(raw["variants"]).map { |v| v["price"] }.compact
+              amounts = ["0"] if amounts.empty?
+              minors = amounts.map { |a| Portage::Ucp::Support::Amounts.decimal_to_minor(a) }
+              Portage::Ucp::PriceRange.new(min: Portage::Ucp::Price.new(amount: minors.min, currency: nil),
+                                           max: Portage::Ucp::Price.new(amount: minors.max, currency: nil))
+            end
+
+            # Classifier on product_type and tags (the plan's inputs), top
+            # three ids, then the store's own product_type as a merchant
+            # category.
+            def categories(raw, classify)
+              text = [raw["product_type"], *Array(raw["tags"])].compact.join(" ")
+              ids = text.strip.empty? ? [] : classify.call(text).first(MAX_CATEGORIES)
+              google = ids.map { |id| Portage::Ucp::Category.new(value: id, taxonomy: TAXONOMY) }
+              type = raw["product_type"].to_s.strip
+              type.empty? ? google : google + [Portage::Ucp::Category.new(value: type, taxonomy: "merchant")]
+            end
+          end
+        end
+      end
+    end
+  end
+end