shopify_toolkit 0.3.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 457f7f3d4a71f0d16b2626673522a0c39fff7bf0cd0d77108dfad5be5ebed8dc
-  data.tar.gz: bbfc1ddfb371307e3eacfdcc24896628772886bb89e9333b5f0efab79dd34e42
+  metadata.gz: fbc1361f6cf3ce45a4b6d004f55cc98b4c9f748c2863e281874cc48f085e7b9d
+  data.tar.gz: 2e9a2fc920f7f7178f5f4ea3ccc945e6ac0c4fb1d50a426d77708888837a4941
 SHA512:
-  metadata.gz: 2d81a0a15f9316488ffa6a7f56b5bbcab71196c8802568775d624802f9cba40ede8043d7e29e25008bc4e716bb01cdc5a299e4c542be92a53e1b681ef0c38b3e
-  data.tar.gz: 1896abe675d312bd57352cae7ca5e19a217055b551ed1ae992f1e453985c31361ea2d515333b6a5f129dbab4aab18ce0bb716faae49fc01615e76e6597bb7242
+  metadata.gz: 44168636617828f3420d2fd0da7322c962f0b1a7a34e57cf9fe8642acc67d1dfe22dd5fabc934f0ba671e83eecf1623f47dd99f37c98821ef8689b81df91bc7f
+  data.tar.gz: 3fa125127d19a08be48ef8a2165628816653527f272fb0cd352962ff1f5bdb55d5c2a2d8ea08bf3eabd174278e4d9d5777fcee2988d0ee6956b52ff464686c8e

data/README.md

@@ -11,9 +11,14 @@ A toolkit for working with Custom Shopify Apps built on Rails.
 ## Features/Roadmap
 
 - [x] Shopify/Matrixify CSV tools
-- [ ] Metafield/Metaobject migrations (just like ActiveRecord migrations, but for Shopify!)
-  - [x] Metafield Definitions management API
-  - [ ] Metaobject Definitions management API
+- [x] Metafield/Metaobject migrations (just like ActiveRecord migrations, but for Shopify!)
+- [x] Metafield Definitions management API
+- [x] Metaobject Definitions management API
+  - [x] Create
+  - [x] Update
+  - [x] Find
+  - [ ] Delete
+- [ ] Metaobject Instances management API
 - [ ] GraphQL Admin API code generation (syntax checking, etc)
 - [ ] GraphQL Admin API client with built-in rate limiting
 - [ ] GraphQL Admin API client with built-in caching
@@ -30,38 +35,51 @@ bundle add shopify_toolkit
 
 ## Usage
 
-### Migrating Metafields definitions using ActiveRecord Migrations
+### Migrating Metafields and Metaobjects
 
 Within a Rails application created with ShopifyApp, generate a new migration file:
 
 ```bash
-rails generate migration AddMetafieldDefinitions
+touch config/shopify/migrate/$(date +%Y%m%d%H%M%S)_add_product_press_releases.rb
 ```
 
-Include the `ShopifyToolkit::MetafieldStatements` module in your migration file
-in order to use the metafield statements:
-
+Then, add the following code to the migration file:
 ```ruby
-class AddMetafieldDefinitions < ActiveRecord::Migration[7.0]
-  include ShopifyToolkit::MetafieldStatements
-
+# config/shopify/migrate/20250528130134_add_product_press_releases.rb
+class AddProductPressReleases < ShopifyToolkit::Migration
   def up
-    Shop.first!.with_shopify_session do
-      create_metafield :products, :my_metafield, :single_line_text_field, name: "My Metafield"
-    end
+    create_metaobject_definition :press_release,
+      name: "Press Release",
+      displayNameKey: "name",
+      access: { storefront: "PUBLIC_READ" },
+      capabilities: {
+        onlineStore: { enabled: false },
+        publishable: { enabled: true },
+        translatable: { enabled: true },
+        renderable: { enabled: false },
+      },
+      fieldDefinitions: [
+        { key: "name", name: "Title", required: true, type: "single_line_text_field" },
+        { key: "body", name: "Body", required: true, type: "multi_line_text_field" },
+      ]
+
+    metaobject_definition_id = get_metaobject_definition_gid :press_release
+
+    create_metafield :products, :press_release, :metaobject_reference, name: "Press Release", validations: [
+      { name: "metaobject_definition_id", value: metaobject_definition_id }
+    ]
   end
 
   def down
-    Shop.first!.with_shopify_session do
-      remove_metafield :products, :my_metafield
-    end
+    # Noop. We don't want to remove the metaobject definition, since it might be populated with data.
   end
 end
 ```
-Then run the migration:
+
+Then run the migrations:
 
 ```bash
-rails db:migrate
+bundle exec shopify-toolkit migrate
 ```
 
 ### Creating a Metafield Schema Definition

data/exe/shopify-toolkit

@@ -1,72 +1,5 @@
 #!/usr/bin/env ruby
 
-require 'csv'
-require 'active_record'
-require 'thor'
-require 'tmpdir'
 require 'shopify_toolkit'
 
-class ShopifyToolkit::CommandLine < Thor
-  RESERVED_COLUMN_NAMES = %w[select type id]
-
-  class Result < ActiveRecord::Base
-    def self.comments
-      distinct.pluck(:import_comment)
-    end
-
-    def self.with_comment(text)
-      where("import_comment LIKE ?", "%#{text}%")
-    end
-  end
-
-  desc "analyze CSV_PATH", "Analyze results file at path CSV_PATH"
-  method_option :force_import, type: :boolean, default: false
-  method_option :tmp_dir, type: :string, default: Dir.tmpdir
-  def analyze(csv_path)
-    csv_path = File.expand_path(csv_path)
-    underscore = ->(string) { string.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/(^_+|_+$)/, "") }
-    csv = CSV.open(csv_path, liberal_parsing:true )
-    header_to_column = -> { RESERVED_COLUMN_NAMES.include?(_1.to_s) ? "#{_1}_1" : _1 }
-    headers = csv.shift.map(&underscore).map(&header_to_column)
-    basename = File.basename csv_path
-    database = "#{options[:tmp_dir]}/shopify-toolkit-analyze-#{underscore[basename]}.sqlite3"
-    should_import = options[:force_import] || !File.exist?(database)
-    to_record = ->(row) { headers.zip(row.each{ |c| c.delete!("\u0000") if String === c }).to_h.transform_keys(&header_to_column) }
-
-    File.delete(database) if should_import && File.exist?(database)
-
-    ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database:)
-
-    if should_import
-      puts "==> Importing #{csv_path} into #{database}"
-      ActiveRecord::Schema.define do
-        create_table :results, force: true do |t|
-          t.json :data
-          headers.each { |header| t.string header }
-        end
-        add_index :results, :import_result if headers.include?('import_result')
-      end
-      csv.each_slice(5000) { |rows| print "."; Result.insert_all(rows.map(&to_record)) }
-      puts
-    end
-
-    puts "==> Starting console for #{basename}"
-    require "irb"
-    IRB.conf[:IRB_NAME] = basename
-    Result.class_eval { binding.irb(show_code: false) }
-  end
-
-  desc "schema_load", 'Load schema from "config/shopify/schema.rb"'
-  def schema_load
-    require "./config/environment"
-    ::Shop.sole.with_shopify_session { ShopifyToolkit::Schema.load! }
-  end
-
-  desc "schema_dump", 'Dump schema to "config/shopify/schema.rb"'
-  def schema_dump
-    require "./config/environment"
-    ::Shop.sole.with_shopify_session { ShopifyToolkit::Schema.dump! }
-  end
-end
-
 ShopifyToolkit::CommandLine.start(ARGV)

data/lib/shopify_toolkit/admin_client.rb

@@ -1,3 +1,5 @@
+require "shopify_api"
+
 module ShopifyToolkit::AdminClient
   API_VERSION = "2024-10"
 

data/lib/shopify_toolkit/command_line.rb

@@ -0,0 +1,89 @@
+require 'csv'
+require 'active_record'
+require 'thor'
+require 'tmpdir'
+
+class ShopifyToolkit::CommandLine < Thor
+  RESERVED_COLUMN_NAMES = %w[select type id]
+
+  class Result < ActiveRecord::Base
+    def self.comments
+      distinct.pluck(:import_comment)
+    end
+
+    def self.with_comment(text)
+      where("import_comment LIKE ?", "%#{text}%")
+    end
+  end
+
+  desc "analyze CSV_PATH", "Analyze results file at path CSV_PATH"
+  method_option :force_import, type: :boolean, default: false
+  method_option :tmp_dir, type: :string, default: Dir.tmpdir
+  def analyze(csv_path)
+    csv_path = File.expand_path(csv_path)
+    underscore = ->(string) { string.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/(^_+|_+$)/, "") }
+    csv = CSV.open(csv_path, liberal_parsing:true )
+    header_to_column = -> { RESERVED_COLUMN_NAMES.include?(_1.to_s) ? "#{_1}_1" : _1 }
+    headers = csv.shift.map(&underscore).map(&header_to_column)
+    basename = File.basename csv_path
+    database = "#{options[:tmp_dir]}/shopify-toolkit-analyze-#{underscore[basename]}.sqlite3"
+    should_import = options[:force_import] || !File.exist?(database)
+    to_record = ->(row) { headers.zip(row.each{ |c| c.delete!("\u0000") if String === c }).to_h.transform_keys(&header_to_column) }
+
+    File.delete(database) if should_import && File.exist?(database)
+
+    ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database:)
+
+    if should_import
+      puts "==> Importing #{csv_path} into #{database}"
+      ActiveRecord::Schema.define do
+        create_table :results, force: true do |t|
+          t.json :data
+          headers.each { |header| t.string header }
+        end
+        add_index :results, :import_result if headers.include?('import_result')
+      end
+      csv.each_slice(5000) { |rows| print "."; Result.insert_all(rows.map(&to_record)) }
+      puts
+    end
+
+    puts "==> Starting console for #{basename}"
+    require "irb"
+    IRB.conf[:IRB_NAME] = basename
+    Result.class_eval { binding.irb(show_code: false) }
+  end
+
+  desc "migrate", "Run migrations"
+  def migrate
+    require "./config/environment"
+    ::Shop.sole.with_shopify_session { ShopifyToolkit::Migrator.new.up }
+  end
+
+  desc "rollback", "Rollback last migration"
+  def rollback
+    require "./config/environment"
+    ::Shop.sole.with_shopify_session { ShopifyToolkit::Migrator.new.down }
+  end
+
+  desc "redo", "Run migrations down and up again"
+  def redo
+    require "./config/environment"
+    ::Shop.sole.with_shopify_session { ShopifyToolkit::Migrator.new.redo }
+  end
+
+  desc "schema_load", 'Load schema from "config/shopify/schema.rb"'
+  def schema_load
+    require "./config/environment"
+    ::Shop.sole.with_shopify_session { ShopifyToolkit::Schema.load! }
+  end
+
+  desc "schema_dump", 'Dump schema to "config/shopify/schema.rb"'
+  def schema_dump
+    require "./config/environment"
+    ::Shop.sole.with_shopify_session { ShopifyToolkit::Schema.dump! }
+  end
+
+  def self.exit_on_failure?
+    true
+  end
+end

data/lib/shopify_toolkit/metafield_statements.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "shopify_toolkit/migration/logging"
-require "shopify_toolkit/admin_client"
 require "active_support/concern"
 
 module ShopifyToolkit::MetafieldStatements

data/lib/shopify_toolkit/metaobject_statements.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module ShopifyToolkit::MetaobjectStatements
+  extend ActiveSupport::Concern
+  include ShopifyToolkit::Migration::Logging
+  include ShopifyToolkit::AdminClient
+
+  def self.log_time(method_name)
+    current_method = instance_method(method_name)
+    define_method(method_name) do |*args, **kwargs, &block|
+      say_with_time("#{method_name}(#{args.map(&:inspect).join(', ')})") { current_method.bind(self).call(*args, **kwargs, &block) }
+    end
+  end
+
+  # create_metafield :products, :my_metafield, :single_line_text_field, name: "Prova"
+  # @param namespace: if nil the metafield will be app-specific (default: :custom)
+  log_time \
+  def create_metaobject_definition(type, **options)
+    # Skip creation if metafield already exists
+    existing_gid = get_metaobject_definition_gid(type)
+    if existing_gid
+      say "Metaobject #{type} already exists, skipping creation"
+      return existing_gid
+    end
+
+    # https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/metafieldDefinitionCreate
+    query =
+      "# GraphQL
+      mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {
+        metaobjectDefinitionCreate(definition: $definition) {
+          metaobjectDefinition {
+            id
+            name
+            type
+            fieldDefinitions {
+              name
+              key
+            }
+          }
+          userErrors {
+            field
+            message
+            code
+          }
+        }
+      }
+      "
+    variables = { definition: { type:, **options } }
+
+    shopify_admin_client
+      .query(query:, variables:)
+      .tap { handle_shopify_admin_client_errors(_1, "data.metaobjectDefinitionCreate.userErrors") }
+  end
+
+  def get_metaobject_definition_gid(type)
+    result =
+      shopify_admin_client
+        .query(
+          query:
+            "# GraphQL
+              query GetMetaobjectDefinitionID($type: String!) {
+                metaobjectDefinitionByType(type: $type) {
+                  id
+                }
+              }",
+          variables: { type: type.to_s },
+        )
+        .tap { handle_shopify_admin_client_errors(_1) }
+        .body
+
+    result.dig("data", "metaobjectDefinitionByType", "id")
+  end
+
+  def update_metaobject_definition(type, **options)
+    existing_gid = get_metaobject_definition_gid(type)
+
+    raise "Metaobject #{type} does not exist" unless existing_gid
+
+    # https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/metaobjectDefinitionUpdate
+    query =
+      "# GraphQL
+      mutation UpdateMetaobjectDefinition($id: ID!, $definition: MetaobjectDefinitionUpdateInput!) {
+        metaobjectDefinitionUpdate(id: $id, definition: $definition) {
+          metaobjectDefinition {
+            id
+            name
+            type
+            fieldDefinitions {
+              name
+              key
+            }
+          }
+          userErrors {
+            field
+            message
+            code
+          }
+        }
+      }
+    "
+    variables = { id: existing_gid, definition: { **options } }
+
+    shopify_admin_client
+      .query(query:, variables:)
+      .tap { handle_shopify_admin_client_errors(_1, "data.metaobjectDefinitionUpdate.userErrors") }
+  end
+
+  def self.define(&block)
+    context = Object.new
+    context.extend(self)
+
+    context.instance_eval(&block) if block_given?(&block)
+    context
+  end
+end

data/lib/shopify_toolkit/migration.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "active_support/benchmark"
+
+class ShopifyToolkit::Migration
+  include ShopifyToolkit::AdminClient
+  include ShopifyToolkit::MetafieldStatements
+  include ShopifyToolkit::MetaobjectStatements
+  include ShopifyToolkit::Migration::Logging
+
+  class IrreversibleMigration < StandardError
+  end
+
+  def logger
+    @logger ||= ActiveSupport::Logger.new(STDOUT).tap do |logger|
+      logger.formatter = proc do |severity, datetime, progname, msg|
+        "#{severity}: #{msg}\n"
+      end
+    end
+  end
+
+  def self.[](api_version)
+    klass = Class.new(self)
+    klass.const_set(:API_VERSION, api_version)
+    klass
+  end
+
+  attr_reader :name, :version
+
+  def initialize(name, version)
+    @name    = name
+    @version = version
+  end
+
+  def announce(message)
+    super "#{version} #{name}: #{message}"
+  end
+
+  def migrate(direction)
+    case direction
+    when :up
+      announce("migrating")
+      time_elapsed = ActiveSupport::Benchmark.realtime { up }
+      announce("migrated (%.4fs)" % time_elapsed)
+
+    when :down
+      announce("reverting")
+      time_elapsed = ActiveSupport::Benchmark.realtime { down }
+      announce("reverted (%.4fs)" % time_elapsed)
+
+    else
+      raise ArgumentError, "Unknown migration direction: #{direction}"
+    end
+  end
+
+  def up
+    # Implement in subclass
+  end
+
+  def down
+    raise IrreversibleMigration
+  end
+end

data/lib/shopify_toolkit/migrator.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "active_support/benchmarkable"
+require "active_support/core_ext/module/delegation"
+
+class ShopifyToolkit::Migrator # :nodoc:
+  include ShopifyToolkit::AdminClient
+  include ShopifyToolkit::MetafieldStatements
+
+  singleton_class.attr_accessor :migrations_paths
+  self.migrations_paths = ["config/shopify/migrate"]
+
+  attr_reader :migrated_versions, :migrations, :migrations_paths
+
+  def initialize(migrations_paths: self.class.migrations_paths)
+    @migrations_paths  = migrations_paths
+    @migrated_versions = read_or_create_metafield["migrated_versions"]
+    @migrations        = load_migrations # [MigrationProxy<Migration1>, MigrationProxy<Migration2>, ...]
+  end
+
+  def current_version
+    migrated.max || 0
+  end
+
+  def up
+    pending_migrations = migrations.reject { migrated_versions.include?(_1.version) }
+
+    pending_migrations.each do |migration|
+      migration.migrate(:up)
+      migrated_versions << migration.version
+    end
+  ensure
+    update_metafield
+  end
+
+  def executed_migrations
+    migrations.select { migrated_versions.include?(_1.version) }
+  end
+
+  def down
+    # For now we'll just rollback the last one
+    executed_migrations.last(1).each do |migration|
+      migration.migrate(:down)
+      migrated_versions.delete(migration.version)
+    end
+  ensure
+    update_metafield
+  end
+
+  def query(query, **variables)
+    shopify_admin_client
+      .query(query:, variables:)
+      .tap { handle_shopify_admin_client_errors(_1) }
+      .body
+      .dig("data")
+  end
+
+  def update_metafield
+    namespace = :shopify_toolkit
+    key = :migrations
+
+    value = { "migrated_versions" => migrated_versions.to_a.sort }.to_json
+
+    owner_id = query(%(query GetShopGId { shop { id } })).dig("shop", "id")
+
+    query = <<~GRAPHQL
+      mutation metafieldsSet($metafields: [MetafieldsSetInput!]!) {
+        metafieldsSet(metafields: $metafields) {
+          userErrors {
+            field
+            message
+          }
+        }
+      }
+    GRAPHQL
+    query(query, metafields: [{ namespace:, key:, ownerId: owner_id, value: }])
+
+    nil
+  end
+
+  def read_or_create_metafield
+    namespace = :shopify_toolkit
+    key = :migrations
+
+    value = query(
+      "query ShopMetafield($namespace: String!, $key: String!) {shop {metafield(namespace: $namespace, key: $key) {value}}}",
+      namespace:, key:,
+    ).dig("shop", "metafield", "value")
+
+    if value.nil?
+      create_metafield :shop, key, :json, namespace:, name: "Migrations metadata"
+      return { "migrated_versions" => [] }
+    end
+
+    JSON.parse(value)
+  end
+
+  def redo
+    down
+    up
+  end
+
+  def migration_files
+    paths = Array(migrations_paths)
+    Dir[*paths.flat_map { |path| "#{path}/**/[0-9]*_*.rb" }]
+  end
+
+  def parse_migration_filename(filename)
+    File.basename(filename).scan(/\A([0-9]+)_([_a-z0-9]*)\.?([_a-z0-9]*)?\.rb\z/).first
+  end
+
+  def load_migrations
+    migrations = migration_files.map do |file|
+      version, name, scope = parse_migration_filename(file)
+      raise "missing version #{file}" unless version
+      raise "missing name #{file}" unless name
+      version = version.to_i
+      name = name.camelize
+
+      MigrationProxy.new(name, version, file, scope)
+    end
+
+    migrations.sort_by(&:version)
+  end
+
+  # MigrationProxy is used to defer loading of the actual migration classes
+  # until they are needed
+  MigrationProxy = Struct.new(:name, :version, :filename, :scope) do
+    def initialize(name, version, filename, scope)
+      super
+      @migration = nil
+    end
+
+    def basename
+      File.basename(filename)
+    end
+
+    delegate :migrate, :up, :down, :announce, :say, :say_with_time, to: :migration
+
+    private
+      def migration
+        @migration ||= load_migration
+      end
+
+      def load_migration
+        Object.send(:remove_const, name) rescue nil
+
+        load(File.expand_path(filename))
+        name.constantize.new(name, version)
+      end
+  end
+end

data/lib/shopify_toolkit/schema.rb

@@ -3,6 +3,7 @@
 require "stringio"
 require "shopify_api"
 require "rails"
+require "active_support/core_ext/module/delegation"
 
 module ShopifyToolkit::Schema
   extend self

data/lib/shopify_toolkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ShopifyToolkit
-  VERSION = "0.3.5"
+  VERSION = "0.5.0"
 end

data/lib/shopify_toolkit.rb

@@ -4,7 +4,6 @@ require_relative "shopify_toolkit/version"
 require "zeitwerk"
 
 module ShopifyToolkit
-
   def self.loader
     @loader ||= Zeitwerk::Loader.for_gem
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shopify_toolkit
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.5.0
 platform: ruby
 authors:
 - Elia Schito
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-24 00:00:00.000000000 Z
+date: 2025-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -111,8 +111,12 @@ files:
 - exe/shopify-toolkit
 - lib/shopify_toolkit.rb
 - lib/shopify_toolkit/admin_client.rb
+- lib/shopify_toolkit/command_line.rb
 - lib/shopify_toolkit/metafield_statements.rb
+- lib/shopify_toolkit/metaobject_statements.rb
+- lib/shopify_toolkit/migration.rb
 - lib/shopify_toolkit/migration/logging.rb
+- lib/shopify_toolkit/migrator.rb
 - lib/shopify_toolkit/schema.rb
 - lib/shopify_toolkit/version.rb
 - sig/shopify_toolkit.rbs