shopify_toolkit 0.1.0.pre → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cece3645d02f939f0c4e534edd97ad5150843e85c5c54f639f07ddd480921105
-  data.tar.gz: 7e2e8a0bca62733fe38415178e08dedbf01e62455902d0c82044d25f46cdfab4
+  metadata.gz: e21a90f2ee3abbe3ca01f52a8b3f559437d357e41e649d2351a5740c83dfcb1c
+  data.tar.gz: 5e731cba7ace9bf63e2e68203efe6a12db03642a2fbe88d3db34ed91cc903450
 SHA512:
-  metadata.gz: 0042f15676cbc63112d7c7b68ef249a657e37c6a5dce70e4d496479bc8c1146f5ca2240210162a57ef07038b25fbbe01a59226632d28e366546e4a35ef8b539e
-  data.tar.gz: 9927b5dbcb3c072c263b81fef3a6d7775ecf6fbed67fca668cccb8a8116002c2e42c522b06469608cdce7a7d7ab86a69303765329424e1c5b15c44c8180dea6b
+  metadata.gz: 87dd02b8491e762cf1e3ffa8e2cada8b8c243d921b35e69f7978dad66d333fe767b463b61e9920600bfbd312c438734342adc6306d656efe07efa63bab918b83
+  data.tar.gz: e1a5daad1b1dd2f8239f8e2c45b5b988c8864a9536533656fc76a66cd7c420df9be66bc441f58e5a1786019bac4d284e515367d6aa3d1b3ce672f0354023fdbc

data/README.md

@@ -4,8 +4,10 @@ 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!)
-- [ ] Shopify CSV Import/Export tools
+  - [x] Metafield Definitions management API
+  - [ ] Metaobject Definitions 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
@@ -22,7 +24,87 @@ bundle add shopify_toolkit
 
 ## Usage
 
-TODO
+### Migrating Metafields definitions using ActiveRecord Migrations
+
+Within a Rails application created with ShopifyApp, generate a new migration file:
+
+```bash
+rails generate migration AddMetafieldDefinitions
+```
+
+Include the `ShopifyToolkit::MetafieldStatements` module in your migration file
+in order to use the metafield statements:
+
+```ruby
+class AddMetafieldDefinitions < ActiveRecord::Migration[7.0]
+  include ShopifyToolkit::MetafieldStatements
+
+  def up
+    Shop.first!.with_shopify_session do
+      create_metafield :products, :my_metafield, :single_line_text_field, name: "My Metafield"
+    end
+  end
+
+  def down
+    Shop.first!.with_shopify_session do
+      remove_metafield :products, :my_metafield
+    end
+  end
+end
+```
+Then run the migration:
+
+```bash
+rails db:migrate
+```
+
+### Creating a Metafield Schema Definition
+
+You can also create a metafield schema definition file to define your metafields in a more structured way. This is useful for keeping track of your metafields and their definitions.
+
+```rb
+# config/shopify/schema.rb
+
+ShopifyToolkit::MetafieldSchema.define do
+  # Define your metafield schema here
+  # For example:
+  create_metafield :products, :my_metafield, :single_line_text_field, name: "My Metafield"
+end
+```
+
+### Analyzing a Matrixify CSV Result files
+
+Matrixify is a popular Shopify app that allows you to import/export data from Shopify using CSV files. The CSV files that Matrixify generates are very verbose and can be difficult to work with. This tool allows you to analyze the CSV files and extract the data you need.
+
+The tool will import the file into a local SQLite database
+and open a console for you to run queries against the data
+using ActiveRecord.
+
+```shell
+shopify-csv analyze products-result.csv --force-import
+==> Importing products-result.csv into /var/folders/hn/z7b7s1kj3js4k7_qk3lj27kr0000gn/T/shopify-toolkit-analyze-products_result_csv.sqlite3
+-- create_table(:results, {:force=>true})
+   -> 0.0181s
+-- add_index(:results, :import_result)
+   -> 0.0028s
+........................
+==> Starting console for products-result.csv
+>> comments
+=>
+["UPDATE: Found by Handle | Assuming MERGE for Variant Command | Assuming MERGE for Tags Command | Variants updated by SKU: 1",
+ "UPDATE: Found by Handle | Assuming MERGE for Variant Command | Assuming MERGE for Tags Command | Variants updated by SKU: 1 | Warning: The following media were not uploaded to Shopify: [https://mymedia.com/image.jpg: Error downloading from Web: 302 Moved Temporarily]",
+ ...]
+>> first
+#<ShopifyCSV::Result:0x0000000300bf1668
+ id: 1,
+ data: nil,
+ handle: "my-product",
+ title: "My Product",
+ import_result: "OK",
+ import_comment: "UPDATE: Found by Handle | Assuming MERGE for Varia...">
+>> count
+=> 116103
+```
 
 ## Development
 

data/exe/shopify-toolkit

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+
+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
+end
+
+ShopifyToolkit::CommandLine.start(ARGV)

data/lib/shopify_toolkit/admin_client.rb

@@ -0,0 +1,39 @@
+module ShopifyToolkit::AdminClient
+  API_VERSION = "2024-10"
+
+  def api_version
+    API_VERSION
+  end
+
+  def shopify_admin_client
+    @shopify_admin_client ||=
+      ShopifyAPI::Clients::Graphql::Admin.new(session: ShopifyAPI::Context.active_session, api_version:)
+  end
+
+  def handle_shopify_admin_client_errors(response, *user_error_paths)
+    if response.code != 200
+      logger.error "Error querying Shopify Admin API: #{response.inspect}"
+      raise "Error querying Shopify Admin API: #{response.inspect}"
+    end
+
+    response
+      .body
+      .dig("errors")
+      .to_a
+      .each do |error|
+        logger.error "Error querying Shopify Admin API: #{error.inspect}"
+        raise "Error querying Shopify Admin API: #{error.inspect}"
+      end
+
+    user_error_paths.each do |path|
+      response
+        .body
+        .dig(*path.split("."))
+        .to_a
+        .each do |error|
+          logger.error "Error querying Shopify Admin API: #{error.inspect} (#{path})"
+          raise "Error querying Shopify Admin API: #{error.inspect} (#{path})"
+        end
+    end
+  end
+end

data/lib/shopify_toolkit/metafield_statements.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "shopify_toolkit/migration/logging"
+require "shopify_toolkit/admin_client"
+
+module ShopifyToolkit::MetafieldStatements
+  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_metafield(owner_type, key, type, namespace: :custom, name:, **options)
+    ownerType = owner_type.to_s.singularize.upcase # Eg. "PRODUCT"
+
+    # https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/metafieldDefinitionCreate
+    query =
+      "# GraphQL
+        mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
+          metafieldDefinitionCreate(definition: $definition) {
+            createdDefinition {
+              id
+              key
+            }
+            userErrors {
+              field
+              message
+              code
+            }
+          }
+        }
+      "
+    variables = { definition: { ownerType:, key:, type:, name:, namespace:, **options } }
+
+    shopify_admin_client
+      .query(query:, variables:)
+      .tap { handle_shopify_admin_client_errors(_1, "metafieldDefinitionCreate.userErrors") }
+  end
+
+  def get_metafield_gid(owner_type, key, namespace: :custom)
+    ownerType = owner_type.to_s.singularize.upcase # Eg. "PRODUCT"
+
+    result =
+      shopify_admin_client
+        .query(
+          query:
+            "# GraphQL
+              query FindMetafieldDefinition($ownerType: MetafieldOwnerType!, $key: String!) {
+                metafieldDefinitions(first: 1, ownerType: $ownerType, key: $key) {
+                  nodes { id }
+                }
+              }",
+          variables: {
+            ownerType:,
+            key:,
+            namespace:,
+          },
+        )
+        .tap { handle_shopify_admin_client_errors(_1) }
+        .body
+
+    result.dig("data", "metafieldDefinitions", "nodes", 0, "id") or
+      raise "Metafield not found for #{owner_type}##{namespace}:#{key}"
+  end
+
+  log_time \
+  def remove_metafield(owner_type, key, namespace: :custom, delete_associated_metafields: false, **options)
+    if namespace == nil && delete_associated_metafields == false
+      raise ArgumentError,
+            "For reserved namespaces, you must delete all associated metafields (delete_associated_metafields: true)"
+    end
+
+    shopify_admin_client
+      .query(
+        # Documentation: https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/metafieldDefinitionDelete
+        query:
+          "# GraphQL
+            mutation DeleteMetafieldDefinition($id: ID!, $deleteAllAssociatedMetafields: Boolean!) {
+              metafieldDefinitionDelete(id: $id, deleteAllAssociatedMetafields: $deleteAllAssociatedMetafields) {
+                deletedDefinitionId
+                userErrors {
+                  field
+                  message
+                  code
+                }
+              }
+            }",
+        variables: {
+          id: get_metafield_gid(owner_type, key, namespace: namespace),
+          deleteAllAssociatedMetafields: delete_associated_metafields,
+        },
+      )
+      .tap { handle_shopify_admin_client_errors(_1, "metafieldDefinitionDelete.userErrors") }
+  end
+
+  def update_metafield(owner_type, key, namespace: :custom, **options)
+  log_time \
+    shopify_admin_client
+      .query(
+        # Documentation: https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/metafieldDefinitionUpdate
+        query:
+          "# GraphQL
+            mutation UpdateMetafieldDefinition($definition: MetafieldDefinitionUpdateInput!) {
+              metafieldDefinitionUpdate(definition: $definition) {
+                updatedDefinition {
+                  id
+                  name
+                }
+                userErrors {
+                  field
+                  message
+                  code
+                }
+              }
+            }",
+        variables: {
+          definition: {
+            ownerType: owner_type.to_s.singularize.upcase,
+            key:,
+            namespace:,
+            **options,
+          },
+        },
+      )
+      .tap { handle_shopify_admin_client_errors(_1, "metafieldDefinitionUpdate.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/logging.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ShopifyToolkit::Migration::Logging
+  def write(text = "")
+    puts(text)
+  end
+
+  def announce(message)
+    text = "#{version} #{name}: #{message}"
+    length = [0, 75 - text.length].max
+    write "== %s %s" % [text, "=" * length]
+  end
+
+  # Takes a message argument and outputs it as is.
+  # A second boolean argument can be passed to specify whether to indent or not.
+  def say(message, subitem = false)
+    write "#{subitem ? "   ->" : "--"} #{message}"
+  end
+
+  # Outputs text along with how long it took to run its block.
+  # If the block returns an integer it assumes it is the number of rows affected.
+  def say_with_time(message)
+    say(message)
+    result = nil
+    time_elapsed = ActiveSupport::Benchmark.realtime { result = yield }
+    say "%.4fs" % time_elapsed, :subitem
+    result
+  end
+end

data/lib/shopify_toolkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ShopifyToolkit
-  VERSION = "0.1.0.pre"
+  VERSION = "0.1.0"
 end

data/lib/shopify_toolkit.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "shopify_toolkit/version"
+require "zeitwerk"
 
 module ShopifyToolkit
-  class Error < StandardError; end
-  # Your code goes here...
+
+  def self.loader
+    @loader ||= Zeitwerk::Loader.for_gem
+  end
+
+  loader.setup
+  # loader.eager_load # optionally
 end

metadata

@@ -1,18 +1,75 @@
 --- !ruby/object:Gem::Specification
 name: shopify_toolkit
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre
+  version: 0.1.0
 platform: ruby
 authors:
 - Elia Schito
 - Nebulab Team
 bindir: exe
 cert_chain: []
-date: 2025-03-14 00:00:00.000000000 Z
-dependencies: []
+date: 2025-04-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: shopify_api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '14.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '14.8'
 email:
 - elia@schito.me
-executables: []
+executables:
+- shopify-toolkit
 extensions: []
 extra_rdoc_files: []
 files:
@@ -20,7 +77,11 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- exe/shopify-toolkit
 - lib/shopify_toolkit.rb
+- lib/shopify_toolkit/admin_client.rb
+- lib/shopify_toolkit/metafield_statements.rb
+- lib/shopify_toolkit/migration/logging.rb
 - lib/shopify_toolkit/version.rb
 - sig/shopify_toolkit.rbs
 homepage: https://github.com/nebulab/shopify_toolkit?tab=readme-ov-file#readme