sf_cli 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d070d17a818ef2dd2030a026e1e3b14a284eb1e4ce1bab9ed46c8f5811c2169
-  data.tar.gz: aa7aafc17f57d6d9df71e6969caad6c756965cfce76ca5583acd73799366b34c
+  metadata.gz: c53d056727e589cb48d79aced7900a9419015ad0840e59b5f4d25361a31468ad
+  data.tar.gz: 491d45e9ce3907f931d07526eb37f9698e8c5b4cd95ffb3f38317244d99ea656
 SHA512:
-  metadata.gz: ddfd91e3ddd1573938d9dbb9c27749eb8054475cee62d5565222f75ad2867fe1abf3dc3c5cc48a452a79991971532f89b233ddf1db491a83b9f28348fdd53eb0
-  data.tar.gz: 9df1154ec04b5acefddc469429163feed1ee432abd517048b0915d046c29d9d30a5e097153aa50a5774085720f91c68f86cda484ada9d667a6140cd15bcbe6bb
+  metadata.gz: a49220a708a8cab60b8ae22f09b4ac805c6b405c3ae0821809012d0cb4d3b34bfd66f69a3429ae4ed70799a0a6cd793c9edcd52e71b2811aaf7a887bdb8db075
+  data.tar.gz: dc8d5efe8ea8001212d448ca71fe874b61625960a6daea6163d459d9603c0d5ccbbf1b8c4795694495e4b1b963100113dd02e9dba56160322e3ab27ebcada2b3

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+## 0.0.5 - 2024-09-08
+- target CLI version is changed: from 2.54.6 to 2.56.7
+- sf data:
+  - add `--bulk` option to query
+  - add query resume
+  - add upsert bulk
+  - add upsert resume
+  - add delete bulk
+  - add delete resume
+  - add resume
+  - add search
+- sf org:
+  - add list
+  - add login access-token
+  - add `--browser` option to login web
+
+## 0.0.4 - 2024-09-02
+- breaking change:
+  - Sf class doesn't exist anymore. You can not write like `sf = SfCli::Sf.new`. Instead of that,  global `sf` method is introduced. You can directly type like `sf.org.display`, which is as almost same usability as the original command. 
+- sf data query:
+  - support child-parent relationship
+  - support parent-children relationship
+  - add `--result-format` option
+- auto generation of \Object Model (experimental)
+  - generates SF \Object Classes automatically
+  - relationship is supported
+
+## 0.0.3 - 2024-08-25
+add command operations:
+
+- sf data get record
+- sf data create record
+- sf data update record
+- sf data delete record
+
+## 0.0.2 - 2024-08-18
+this version up was made by mistake.
+nothing was changed.
+
+## 0.0.1 - 2024-08-18
+support some command operations:
+
+- sf org login web
+- sf display
+- sf data query
+- sf sobject describe
+- sf sobject list
+- sf project generate
+- sf project generate manifest

data/README.rdoc

@@ -2,12 +2,12 @@
 https://badge.fury.io/rb/sf_cli.png
 
 This is a class library for introducing {Salesforce CLI}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_top.htm] to Ruby scripting.<br>
-It is designed to be similar usability to the command line interface.<br>
+It is designed to be similar usability to the original command.<br>
 Currently only *sf* command is the target of development.
 
 == prerequisite
 Salesforce CLI must be installed.<br>
-As of as of August in 2024, ver.2.54.6 is the development target.
+As of as of September in 2024, ver.2.56.7 is the development target.
 
 == install
 === Rubygem
@@ -21,30 +21,52 @@ then,
   $ bundle install
 
 == Examples
+=== Since 0.0.4
+  require 'sf_cli'
+
+  # login to org
+  sf.org.login_web
+
+  # get records
+  sf.data.query 'SELECT Id, Name FROM Account LIMIT 1' # => [{Id: "abc", Name: "account name"}]
+
+  # generate a Salesforce DX project
+  sf.project.generate 'MyProject'
+
+=== Before 0.0.3
   require 'sf_cli/sf'
 
   sf = SfCli::Sf.new
 
   # login to org
   sf.org.login_web
-  sf.org.login_web target_org: :dev  # name an alias to the org, which you're going to log in, for later use. This is needed when you don't use the default org.
 
   # get Account records
   sf.data.query 'SELECT Id, Name FROM Account LIMIT 3' # => returns an array containing 3 records
   
-  Account = Struct.new(:Id, :Name)
-  sf.data.query('SELECT Id, Name From Account Limit 3', model_class: Account)  # returns an array of Account struct object
-
   # generate a Salesforce DX project
   sf.project.generate 'MyProject'
 
+== \Object Model support (experimental, since 0.0.4)
+  require 'sf_cli'
+  require 'sf_cli/sf/model'
+
+  # generates Model Class for Contact and Account
+  SfCli::Sf::Model.generate %w[Contact Account]
+
+  c = Contact.new(:Name => "John Smith")
+  c.Name # => "John Smith"
 
-For more command details, see {Salesforce CLI Command Reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_top.htm]
+  rows = sf.data.query 'SELECT Id, Name, Account.Name From Contact Limit 3', model_class: Contact
+  rows.size # => 3
+  rows.first.Name # => Name of the Contact
+  rows.first.Account.Name # => Name of the Account
 
 == Documents
+The following steps generate *doc* directory, which all documents are generated in.
   $ git clone https://github.com/tmkw/sf_cli.git
   $ cd sf_cli
   $ bundle install
   $ bundle exec rake rdoc
 
-This generates the documents in doc directory.
+*Or*, you can read the same documents online at {rubygems.org}[https://rubygems.org/gems/sf_cli]

data/lib/sf_cli/sf/core/base.rb

@@ -0,0 +1,80 @@
+module SfCli
+  module Sf
+    module Core
+      module Base
+        attr_reader :varbose
+
+        private
+
+        def exec(action, flags: {}, switches: {}, redirection: nil, raw_output: false, format: :json) # :doc:
+          cmd = %|sf #{category} #{action}#{as_flag_options(flags)}#{as_switch_options(switches, format)}#{redirect redirection}|
+          puts cmd if varbose
+
+          return `#{cmd}` if raw_output
+
+          json = JSON.parse `#{cmd}`
+          puts json if varbose
+          raise StandardError.new(json['message']) if json['status'] != 0
+
+          json
+        end
+
+        def category
+          self.class.name.split('::')[-2].downcase
+        end
+
+        def field_value_pairs(hash)
+          return nil if hash.nil?
+          return nil if hash.empty?
+
+          hash.each_with_object([]) do|(k,v), arr|
+            value = v.instance_of?(String) ? %|'#{v}'| : v
+            arr << %(#{k}=#{value})
+          end
+          .join(' ')
+        end
+
+        def as_flag_options(hash)
+          flag_options   = hash.map{|k,v| flag k, v}.reject(&:nil?).join(' ')
+          flag_options   = ' ' + flag_options unless flag_options.empty?
+
+          flag_options
+        end
+
+        def as_switch_options(hash, format)
+          if format.to_sym == :json
+            ' ' + {json: true}.merge(hash).each_with_object([]){|(k,v), arr| arr << %(--#{k}) if v}.join(' ')
+          else
+            return '' if hash.empty?
+            hash.each_with_object([]){|(k,v), arr| arr << %(--#{k}) if v}.join(' ')
+          end
+        end
+
+        def flag(name, arg)
+          arg ? %(--#{name} #{arg}) : nil
+        end
+
+        def os
+          @os ||= ENV['OS']
+        end
+
+        def redirect(option)
+          case option
+          when :null_stderr
+            null_stderr_redirection
+          else
+          end
+        end
+
+        def null_stderr_redirection
+          @null_stderr_redirection ||=
+            if os.eql?('Windows_NT')
+              ' 2>nul'
+            else
+              ' 2> /dev/null'
+            end
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/data/bulk_result_v2.rb

@@ -0,0 +1,77 @@
+module SfCli
+  module Sf
+    module Data
+      #
+      # Bulk Job information.
+      #
+      # You can check the job status using the following method:
+      # - opened?
+      # - upload_completed?
+      # - in_progress?
+      # - completed?
+      # ==== example:
+      #   result = sf.data.delete_resume job_id: jobinfo.id
+      #   puts 'yey!' if result.job_info.completed? # the job has completed
+      #
+      # For more details, see {the guide document}[https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/bulk_api_2_job_states.htm]
+      #
+      JobInfo = Struct.new(
+        :id,
+        :operation,
+        :object,
+        :createdById,
+        :createdDate,
+        :systemModstamp,
+        :state,
+        :externalIdFieldName,
+        :concurrencyMode,
+        :contentType,
+        :apiVersion,
+        :jobType,
+        :lineEnding,
+        :columnDelimiter,
+        :numberRecordsProcessed,
+        :numberRecordsFailed,
+        :retries,
+        :totalProcessingTime,
+        :apiActiveProcessingTime,
+        :apexProcessingTime,
+        :isPkChunkingSupported
+      ) do
+        def opened?
+          state == 'Open'
+        end
+
+        def upload_completed?
+          state == 'UploadComplete'
+        end
+
+        def in_progress?
+          state == 'InProgress'
+        end
+
+        def completed?
+          state == 'JobComplete'
+        end
+
+        def failed?
+          state == 'Failed'
+        end
+
+        def aborted?
+          state == 'Aborted'
+        end
+      end
+
+      #
+      # Records processed by Bulk API
+      #
+      BulkRecordsV2 = Struct.new(:successfulResults, :failedResults, :unprocessedRecords)
+
+      #
+      # Bulk Result information that contains JobInfo and BulkRecordsV2
+      #
+      BulkResultV2 = Struct.new(:job_info, :records)
+    end
+  end
+end

data/lib/sf_cli/sf/data/core.rb

@@ -0,0 +1,39 @@
+require_relative '../core/base'
+require_relative './query'
+require_relative './get_record'
+require_relative './update_record'
+require_relative './create_record'
+require_relative './delete_record'
+require_relative './delete_bulk'
+require_relative './delete_resume'
+require_relative './upsert_bulk'
+require_relative './upsert_resume'
+require_relative './resume'
+require_relative './search'
+
+module SfCli
+  module Sf
+    module Data
+      #
+      # ==== description
+      # The class representing *sf* *data*
+      #
+      # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm
+      #
+      class Core
+        include ::SfCli::Sf::Core::Base
+        include Query
+        include GetRecord
+        include UpdateRecord
+        include CreateRecord
+        include DeleteRecord
+        include DeleteBulk
+        include DeleteResume
+        include UpsertBulk
+        include UpsertResume
+        include Resume
+        include Search
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/data/create_record.rb

@@ -0,0 +1,30 @@
+module SfCli::Sf::Data
+  module CreateRecord
+    # create a object record.
+    #
+    # *object_type* --- \Object Type (ex. Account)<br>
+    #
+    # *values* --- field values to be assigned<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # ======
+    #   # create a TheCustomObject record with name and age
+    #   sf.data.create_record :TheCustomObject__c, values: {Name: "John Smith", Age: 33}
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_create_record_unified]
+    #
+    def create_record(object_type, values: {}, target_org: nil)
+      field_values = field_value_pairs(values)
+      flags = {
+        :"sobject"    => object_type,
+        :"values"      => (field_values.nil? ? nil : %|"#{field_values}"|),
+        :"target-org" => target_org,
+      }
+      action = __method__.to_s.tr('_', ' ')
+      json = exec(action, flags: flags, redirection: :null_stderr)
+
+      json['result']['id']
+    end
+  end
+end

data/lib/sf_cli/sf/data/delete_bulk.rb

@@ -0,0 +1,47 @@
+require_relative './bulk_result_v2'
+
+module SfCli::Sf::Data
+  module DeleteBulk
+    # delete records using Bulk API 2.0
+    #
+    # *file* --- a CSV file, which is written record IDs to delete<br>
+    #
+    # *sobject* --- \Object Type (ex. Account)<br>
+    #
+    # *timeout* --- max minutes to wait for the job complete the task.<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # ======
+    #   # start a delete job
+    #   jobinfo = sf.data.delete_bulk sobject: :TestCustomObject__c, file: 'delete.csv' # this returns immediately
+    #   jobinfo.id  # => "750J4000003g1OaIAI" it's job ID
+    #
+    #   # you can check if the delete job completed
+    #   sf.data.delete_resume job_id: jobinfo.id
+    #
+    #   # Or, you can wait for the job completion with one try.
+    #   result = sf.data.delete_bulk sobject: :TestCustomObject__c, file: 'delete.csv', timeout: 5  # wait within 5 minutes
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_delete_bulk_unified]
+    #
+    def delete_bulk(file:, sobject:, timeout: nil, target_org: nil)
+      flags = {
+        :"file"    => file,
+        :"sobject"    => sobject,
+        :"wait"      => timeout,
+        :"target-org" => target_org,
+      }
+      action = __method__.to_s.tr('_', ' ')
+      json = exec(action, flags: flags, redirection: :null_stderr)
+
+      job_info =  ::SfCli::Sf::Data::JobInfo.new(**json['result']['jobInfo'])
+      return job_info unless json['result']['records']
+
+      ::SfCli::Sf::Data::BulkResultV2.new(
+        job_info: job_info,
+        records:  ::SfCli::Sf::Data::BulkRecordsV2.new(**json['result']['records'])
+      )
+    end
+  end
+end

data/lib/sf_cli/sf/data/delete_record.rb

@@ -0,0 +1,33 @@
+module SfCli::Sf::Data
+  module DeleteRecord
+    # delete a object record.
+    #
+    # *object_type* --- \Object Type (ex. Account)<br>
+    #
+    # *record_id* --- id of the object<br>
+    #
+    # *where* --- hash object that is used to identify a record<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # ======
+    #   sf.data.delete_record :Hoge__c, record_id: 'xxxxxxx'
+    #   sf.data.delete_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_delete_record_unified]
+    #
+    def delete_record(object_type, record_id: nil, where: nil, target_org: nil)
+      where_conditions = field_value_pairs(where)
+      flags = {
+        :"sobject"    => object_type,
+        :"record-id"  => record_id,
+        :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
+        :"target-org" => target_org,
+      }
+      action = __method__.to_s.tr('_', ' ')
+      json = exec(action, flags: flags, redirection: :null_stderr)
+
+      json['result']['id']
+    end
+  end
+end

data/lib/sf_cli/sf/data/delete_resume.rb

@@ -0,0 +1,47 @@
+require_relative './bulk_result_v2'
+
+module SfCli::Sf::Data
+  module DeleteResume
+    # resume a bulk delete job you previously started with Bulk API 2.0 and return a bulk result object.
+    #
+    # *job_id* ---  job ID you want to resume<br>
+    #
+    # *timeout* --- max minutes to wait for the job complete the task.<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # ======
+    #   # start a delete job
+    #   jobinfo = sf.data.delete_bulk sobject: :TestCustomObject__c, file: 'delete.csv' # this returns immediately
+    #   jobinfo.id  # => "750J4000003g1OaIAI" it's job ID
+    #
+    #   # the job has already started asynchronously.
+    #   # So you should check its progress.
+    #   # if you want to wait for the job complete the task, try 'timeout' option.
+    #   result = sf.data.delete_resume job_id: jobinfo.id
+    #
+    #   puts 'yey!' if result.job_info.completed? # the job has completed
+    #
+    # To know more about a job result, take a look at SfCli::Sf::Data module
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_delete_resume_unified]
+    #
+    def delete_resume(job_id:, timeout: nil, target_org: nil)
+      flags = {
+        :"job-id"     => job_id,
+        :"wait"       => timeout,
+        :"target-org" => target_org,
+      }
+      action = __method__.to_s.tr('_', ' ')
+      json = exec(action, flags: flags, redirection: :null_stderr)
+
+      job_info =  ::SfCli::Sf::Data::JobInfo.new(**json['result']['jobInfo'])
+      return job_info unless json['result']['records']
+
+      ::SfCli::Sf::Data::BulkResultV2.new(
+        job_info: job_info,
+        records:  ::SfCli::Sf::Data::BulkRecordsV2.new(**json['result']['records'])
+      )
+    end
+  end
+end

data/lib/sf_cli/sf/data/get_record.rb

@@ -0,0 +1,42 @@
+module SfCli::Sf::Data
+  module GetRecord
+
+    # get a object record. (eqivalent to *sf* *data* *get* *record*)
+    #
+    # *object_type* --- \Object Type (ex. Account)<br>
+    #
+    # *record_id* --- id of the object<br>
+    #
+    # *where* --- hash object that is used to identify a record<br>
+    #
+    # *target_org* --- an alias of paticular org, not default one<br>
+    #
+    # *model_class* --- the object model class<br>
+    #
+    # ======
+    #   sf.data.get_record :Account, record_id: 'xxxxxxx'
+    #   sf.data.get_record :Account, where: {Name: 'Jonny B.Good', Country: 'USA'}
+    #
+    #   CustomObject = Struct.new(:Id, :Name)
+    #   sf.data.get_record :TheCustomObject__c, record_id: 'xxxxx', model_class: CustomObject  # returns a CustomObject instance
+    #
+    # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_get_record_unified]
+    #
+    def get_record(object_type, record_id: nil, where: nil, target_org: nil, model_class: nil)
+      where_conditions = field_value_pairs(where)
+      flags = {
+        :"sobject"    => object_type,
+        :"record-id"  => record_id,
+        :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
+        :"target-org" => target_org,
+      }
+      action = __method__.to_s.tr('_', ' ')
+      json = exec(action, flags: flags, redirection: :null_stderr)
+
+      result = json['result']
+      result.delete 'attributes'
+
+      model_class ? model_class.new(**result) : result
+    end
+  end
+end

data/lib/sf_cli/sf/data/helper_methods.rb

@@ -0,0 +1,47 @@
+module SfCli
+  module Sf
+    module Data
+      module HelperMethods
+        def prepare_record(hash) # :doc:
+          hash.delete 'attributes'
+
+          hash.keys.each do |k|
+            if parent?(hash[k])
+              hash[k] = prepare_record(hash[k])
+            elsif children?(hash[k])
+              hash[k] = hash[k]['records'].map{|h| prepare_record(h)}
+            end
+          end
+
+          hash
+        end
+
+        def prepare_record_in_bulk_mode(hash) # :doc:
+          hash.keys.each do |k|
+            match_result = /(.*)\.(.*)/.match(k)
+            if match_result
+              hash[match_result[1]] = {match_result[2] => hash[k]}
+              hash.delete k
+            end
+          end
+
+          hash
+        end
+
+        def children?(h)
+          return false unless h.instance_of?(Hash)
+
+          h.has_key? 'records'
+        end
+
+        def parent?(h)
+          return false unless h.instance_of?(Hash)
+
+          h.has_key?('records') == false
+        end
+
+        private :prepare_record, :children?, :parent?
+      end
+    end
+  end
+end