sf_cli 0.0.3 → 0.0.5

data/lib/sf_cli/sf/data/query.rb

@@ -0,0 +1,120 @@
+require_relative './helper_methods'
+require_relative './query_helper'
+
+module SfCli::Sf::Data
+  module Query
+    # get object records using SOQL.
+    #
+    # *soql* --- SOQL<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # *format* --- get the command's raw output. human, csv, json can be available<br>
+    #
+    # *model_class* --- the object model class<br>
+    #
+    # *bulk* --- use Bulk API<br>
+    #
+    # *timeout* --- max minutes to wait for the job complete in Bulk API mode<br>
+    #
+    # ======
+    #   sf.data.query 'SELECT Id, Name FROM Account LIMIT 1' # => [{Id: "abc", Name: "account name"}]
+    #
+    #   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
+    #
+    #   # child-parent relationship is supported
+    #   sf.data.query 'SELECT Id, Name, Account.Name From Contact Limit 1'  #  [{Id: "abc", Name: "contact name", Account: {Name: "account name"}}]
+    #
+    #   # parent-children relationship is supported
+    #   sf.data.query 'SELECT Id, Name, (SELECT Name From Contacts) FROM Account Limit 1'  #  [{Id: "abc", Name: "account name", Contacts: [{Name: "contact name"}]}]
+    #
+    # When using Bulk API, you get the records when the query job completes within time limit.
+    # The method returns a tapple(an array), which changes its contents according to the job result.
+    #
+    # ======
+    #   done, result = sf.data.query 'SELECT Id, Name FROM Account', bulk: true              # max wait 1 min to get result (default)
+    #   done, result = sf.data.query 'SELECT Id, Name FROM Account', bulk: true, timeout: 5  # max wait 5 min to get result
+    #   done, result = sf.data.query 'SELECT Id, Name FROM Account', bulk: true, timeout: 0  # returns immediately
+    #
+    #   rows = result   if done     # if job is completed, the result is an array of record
+    #   job_id = result unless done # if job hasn't completed or it has aborted, the result is the job ID
+    #
+    # 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_query_unified]
+    #
+    # About querying with auto generated object model, see the section {"Object Model support"}[link://files/README_rdoc.html#label-Object+Model+support+-28experimental-2C+since+0.0.4-29] in README.
+    #
+    def query(soql, target_org: nil, format: nil, bulk: false, timeout: nil, model_class: nil)
+      flags    = {
+        :"query"    => %("#{soql}"),
+        :"target-org" => target_org,
+        :"result-format" => format,
+        :"wait" => (bulk ? timeout : nil),
+      }
+      switches = {
+        bulk: bulk,
+      }
+      raw_output = format ? true : false
+      format = format&.to_sym || :json
+
+      result = exec(__method__, flags: flags, switches: switches, redirection: :null_stderr, raw_output: raw_output, format: format)
+
+      return_result(result, raw_output, bulk, model_class)
+    end
+
+    # resume a bulk query job, which you previously started, and get records
+    #
+    # *job_id* ---  job ID you want to resume<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # *format* --- get the command's raw output. human, csv, json can be available<br>
+    #
+    # *model_class* --- the object model class<br>
+    #
+    # ======
+    #   # start a query job
+    #   result1 = sf.data.query 'SELECT Id, Name FROM Account', bulk: true, timeout: 0  # returns immediately
+    #
+    #   result1 # => [false, "<job id>"]
+    #
+    #   # the job has already started asynchronously.
+    #   # So you should check and get the result.
+    #   done, result2 = sf.data.query_resume job_id: result1.last
+    #
+    #   puts 'get the records!' if done # the job has completed
+    #
+    #   result2 # => if done is true, this is an array of record. Otherwise it should be the Job ID.
+    #
+    # 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_query_resume_unified]
+    def query_resume(job_id:, target_org: nil, format: nil, model_class: nil)
+      flags    = {
+        :"bulk-query-id" => job_id,
+        :"target-org" => target_org,
+        :"result-format" => format,
+      }
+      raw_output = format ? true : false
+      format = format || :json
+
+      action = __method__.to_s.tr('_', ' ')
+      result = exec(action, flags: flags, redirection: :null_stderr, raw_output: raw_output, format: format)
+
+      return_result(result, raw_output, true, model_class)
+    end
+
+    def return_result(result, raw_output, bulk, model_class)
+      result_adjuster = 
+        if raw_output
+          RawOutputResultAdjuster.new(result)
+        elsif bulk
+          BulkResultAdjuster.new(result, model_class)
+        else
+          RegularResultAdjuster.new(result, model_class)
+        end
+
+      result_adjuster.get_return_value
+    end
+
+    private :return_result
+  end
+end

data/lib/sf_cli/sf/data/query_helper.rb

@@ -0,0 +1,57 @@
+require_relative './helper_methods'
+
+module SfCli::Sf::Data
+  module Query
+    class RegularResultAdjuster # :nodoc: all
+      include ::SfCli::Sf::Data::HelperMethods
+
+      attr_reader :result, :model_class
+
+      def initialize(result, model_class)
+        @result = result
+        @model_class = model_class
+      end
+
+      def get_return_value
+        result['result']['records'].each_with_object([]) do |h, a|
+          record = prepare_record(h)
+          a << (model_class ? model_class.new(**record) : record)
+        end
+      end
+    end
+
+    class BulkResultAdjuster # :nodoc: all
+      include ::SfCli::Sf::Data::HelperMethods
+
+      attr_reader :result, :model_class
+
+      def initialize(result, model_class)
+        @result = result
+        @model_class = model_class
+      end
+
+      def get_return_value
+        done = result['result']['done']
+        id   = result['result']['id']
+        rows = result['result']['records'].each_with_object([]) do |h, a|
+            record = prepare_record_in_bulk_mode(h)
+            a << (model_class ? model_class.new(**record) : record)
+          end
+
+        done ? [done, rows] : [done, id]
+      end
+    end
+
+    class RawOutputResultAdjuster # :nodoc: all
+      attr_reader :result
+
+      def initialize(result)
+        @result = result
+      end
+
+      def get_return_value
+        result
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/data/resume.rb

@@ -0,0 +1,87 @@
+module SfCli::Sf::Data
+  module Resume
+    JobInfo = Struct.new(
+      :id,
+      :operation,
+      :object,
+      :createdById,
+      :createdDate,
+      :systemModstamp,
+      :state,
+      :concurrencyMode,
+      :contentType,
+      :numberBatchesQueued,
+      :numberBatchesInProgress,
+      :numberBatchesCompleted,
+      :numberBatchesFailed,
+      :numberBatchesTotal,
+      :numberRecordsProcessed,
+      :numberRetries,
+      :apiVersion,
+      :numberRecordsFailed,
+      :totalProcessingTime,
+      :apiActiveProcessingTime,
+      :apexProcessingTime
+    ) 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
+
+    # View the status of a bulk job.
+    #
+    # *job_id* ---  job ID you want to resume<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
+    #
+    #   jobinfo2 = sf.data.resume job_id: jobinfo.id
+    #
+    #   puts 'yey!' if job_info2.completed? # the job has completed
+    #
+    # The job info object has methods to check the job status:
+    # - opened?
+    # - upload_completed?
+    # - in_progress?
+    # - completed?
+    #
+    # To know job status more, take a look at {the bulk API developer guide}[https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/bulk_api_2_job_states.htm]
+    #
+    # 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_resume_unified]
+    #
+    def resume(job_id:, target_org: nil)
+      flags = {
+        :"job-id"     => job_id,
+        :"target-org" => target_org,
+      }
+      json = exec(__method__, flags: flags, redirection: :null_stderr)
+
+      json['result'].delete '$'
+      JobInfo.new(**json['result'])
+    end
+  end
+end

data/lib/sf_cli/sf/data/search.rb

@@ -0,0 +1,50 @@
+module SfCli::Sf::Data
+  module Search
+    # search objects using SOSL.
+    #
+    # *sosl* --- SOSL<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # *format* --- get the command's raw output. human, csv, json can be available. *NOTE*: if you choose csv, csv files are downloaded in current directory<br>
+    #
+    # ======
+    #  # example (in irb):
+    #
+    #  > sf.data.search "FIND {TIM OR YOUNG OR OIL} IN Name Fields"
+    #  =>
+    #  {"Lead"=>["00Q5j00000WgEuDEAV"],
+    #   "Account"=>["0015j00001U2XvNAAV", "0015j00001U2XvMAAV", "0015j00001U2XvJAAV"],
+    #   "Contact"=>
+    #    ["0035j00001HB84BAAT",
+    #     "0035j00001HB84DAAT"],
+    #   "Opportunity"=>
+    #    ["0065j00001XHJLjAAP",
+    #     "0065j00001XHJLTAA5",
+    #     "0065j00001XHJLJAA5"],
+    #   "User"=>["0055j00000CcL2bAAF", "0055j00000CcL1YAAV"]}
+    #
+    # 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_search_unified]
+    #
+    def search(sosl, target_org: nil, format: nil)
+      flags = {
+        :"query"         => %|"#{sosl}"|,
+        :"target-org"    => target_org,
+        :"result-format" => format,
+      }
+      raw_output = format ? true : false
+      format = format&.to_sym || :json
+
+      result = exec(__method__, flags: flags, redirection: :null_stderr, raw_output: raw_output, format: format)
+
+      return if format == :csv
+      return result if format == :human
+
+      result['result']['searchRecords']
+        .group_by{|r| r['attributes']['type']}
+        .each_with_object({}) do |(object_type, records), result|
+          result[object_type] = records.map{|r| r['Id']}
+        end
+    end
+  end
+end

data/lib/sf_cli/sf/data/update_record.rb

@@ -0,0 +1,38 @@
+module SfCli::Sf::Data
+  module UpdateRecord
+
+    # update a object record.
+    #
+    # *object_type* --- \Object Type (ex. Account)<br>
+    #
+    # *record_id* --- id of the object<br>
+    #
+    # *where* --- field values that is used to identify a record<br>
+    #
+    # *values* --- field values for update<br>
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # ==== examples
+    #   sf.data.update_record :Account, record_id: 'xxxxxxx', values: {Name: 'New Account Name'}
+    #   sf.data.update_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}, values: {Phone: 'xxxxx', bar: 2000}
+    #
+    # 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_update_record_unified]
+    #
+    def update_record(object_type, record_id: nil, where: nil, values: nil, target_org: nil)
+      where_conditions  = field_value_pairs(where)
+      field_values      = field_value_pairs(values)
+      flags = {
+        :"sobject"    => object_type,
+        :"record-id"  => record_id,
+        :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
+        :"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/upsert_bulk.rb

@@ -0,0 +1,50 @@
+require_relative './bulk_result_v2'
+
+module SfCli::Sf::Data
+  module UpsertBulk
+    # update records using Bulk API 2.0
+    #
+    # *file* --- a \CSV file for update records<br>
+    #
+    # *sobject* --- \Object Type (ex. Account)<br>
+    #
+    # *external_id* --- Name of the external ID field, or the Id field<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 upsert job
+    #   jobinfo = sf.data.upsert_bulk sobject: :TestCustomObject__c, file: 'upsert.csv' # this returns immediately
+    #   jobinfo.id  # => "750J4000003g1OaIAI" it's job ID
+    #
+    #   # you can check if the upsert job completed
+    #   sf.data.upsert_resume job_id: jobinfo.id
+    #
+    #   # Or, you can wait for the job completion with one try.
+    #   result = sf.data.upsert_bulk sobject: :TestCustomObject__c, file: 'upsert.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_upsert_bulk_unified]
+    #
+    def upsert_bulk(file:, sobject:, external_id:, timeout: nil, target_org: nil)
+      flags = {
+        :"file"    => file,
+        :"sobject"    => sobject,
+        :"external-id"  => external_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/upsert_resume.rb

@@ -0,0 +1,47 @@
+require_relative './bulk_result_v2'
+
+module SfCli::Sf::Data
+  module UpsertResume
+    # resume a bulk upsert 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 upsert job
+    #   jobinfo = sf.data.upsert_bulk sobject: :TestCustomObject__c, file: 'upsert.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.upsert_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_upsert_resume_unified]
+    #
+    def upsert_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/main.rb

@@ -0,0 +1,31 @@
+require 'singleton'
+require 'json'
+
+module SfCli
+  module Sf
+    # ==== description
+    # The entry class of sf command. It is returned by sf method.
+    # With including Singleton module, the instance of this class is guaranteed as singleton.
+    #
+    # ==== examples
+    #   sf             # returns a instance of SfCli::Sf
+    #   sf.org.display # you can follow the similar syntax to the original command by using method chain.
+    #
+    class Main
+      include Singleton
+
+      OPERATION_CATEGORIES = %w[Org Sobject Data Project]
+
+      OPERATION_CATEGORIES.each do |category|
+        require_relative %(#{category.downcase}/core)
+        attr_reader category.downcase.to_sym
+      end
+
+      def initialize
+        OPERATION_CATEGORIES.each do |category|
+          instance_variable_set(:"@#{category.downcase}", Object.const_get(%|::SfCli::Sf::#{category}::Core|).new)
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model/class_definition.rb

@@ -0,0 +1,112 @@
+require_relative './schema'
+
+module SfCli
+  module Sf
+    module Model
+      class ClassDefinition
+        attr_reader :schema
+
+        def initialize(schema)
+          @schema = Schema.new(schema)
+        end
+
+        def to_s
+          <<~Klass
+            Class.new do
+              #{ class_methods }
+
+              field_names.each do |name|
+                attr_accessor name
+              end
+
+              #{ parent_relation_methods }
+              #{ children_relation_methods }
+
+              #{ define_initialize }
+
+              #{ define_to_h }
+            end
+          Klass
+        end
+
+        def define_initialize
+          <<~EOS
+            def initialize(attributes = {})
+              attributes.each do |k, v|
+                field_name = k.to_sym
+                if self.class.field_names.include?(field_name)
+                  #instance_variable_set ('@' + field_name.to_s).to_sym, v
+                  __send__ (field_name.to_s + '='), v
+                elsif self.class.parent_relations.find{|r| r[:name] == field_name}
+                  __send__ (field_name.to_s + '='), v
+                elsif self.class.children_relations.find{|r| r[:name] == field_name}
+                  __send__ (field_name.to_s + '='), (v.nil? ? [] : v)
+                end
+              end
+            end
+          EOS
+        end
+
+        def define_to_h
+          <<~EOS
+            def to_h(keys: nil)
+              self.class.field_names.each_with_object({}) do |name, hash|
+                if keys&.instance_of?(Array)
+                  hash[name] = __send__(name) if keys.include?(name)
+                else
+                  hash[name] = __send__(name)
+                end
+              end
+            end
+          EOS
+        end
+
+        def class_methods
+          <<~EOS
+            class << self
+              def field_names
+                @field_names ||= #{ schema.field_names }
+              end
+
+              def parent_relations
+                @parent_relations ||= #{ schema.parent_relations }
+              end
+
+              def children_relations
+                @children_relations ||= #{ schema.children_relations }
+              end
+            end
+          EOS
+        end
+
+        def parent_relation_methods
+          schema.parent_relations.each_with_object('') do |r, s|
+            s << <<~EOS
+              def #{r[:name]}
+                @#{r[:name]}
+              end
+
+              def #{r[:name]}=(attributes)
+                @#{r[:name]} = #{r[:class_name]}.new(attributes)
+              end
+            EOS
+          end
+        end
+
+        def children_relation_methods
+          schema.children_relations.each_with_object('') do |r, s|
+            s << <<~EOS
+              def #{r[:name]}
+                @#{r[:name]}
+              end
+
+              def #{r[:name]}=(records)
+                @#{r[:name]} = records.map{|attributes| #{r[:class_name]}.new(attributes)}
+              end
+            EOS
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model/generator.rb

@@ -0,0 +1,27 @@
+require_relative '../sobject/core'
+require_relative './class_definition'
+
+module SfCli
+  module Sf
+    module Model
+      class Generator
+        attr_reader :sf_sobject, :target_org
+
+        def initialize(target_org: nil)
+          @sf_sobject = ::SfCli::Sf::Sobject::Core.new
+          @target_org = target_org
+        end
+
+        def generate(object_name)
+          class_definition = ClassDefinition.new(describe object_name)
+
+          instance_eval "::#{object_name} = #{class_definition}"
+        end
+
+        def describe(object_name)
+          sf_sobject.describe object_name, target_org: target_org
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model/schema.rb

@@ -0,0 +1,33 @@
+module SfCli
+  module Sf
+    module Model
+      class Schema
+        attr_reader :schema
+
+        def initialize(schema)
+          @schema = schema
+        end
+
+        def name
+          schema['name']
+        end
+
+        def field_names
+          schema['fields'].map{|f| f['name'].to_sym}
+        end
+
+        def children_relations
+          schema['childRelationships']
+            .select{|r| r['relationshipName'].nil? == false}
+            .map{|r| {name: r['relationshipName'].to_sym, class_name: r['childSObject'].to_sym}}
+        end
+
+        def parent_relations
+          schema['fields']
+            .select{|f| f['relationshipName'].nil? == false && f['referenceTo']&.size > 0}
+            .map{|f| {name: f['relationshipName'].to_sym, class_name: f['referenceTo'].first.to_sym}}
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model.rb

@@ -0,0 +1,21 @@
+require_relative 'model/generator'
+
+module SfCli
+  module Sf
+    #
+    # ==== description
+    # The module for \Object \Model definition and generation
+    #
+    # see the section {"Object Model support"}[link://files/README_rdoc.html#label-Object+Model+support+-28experimental-2C+since+0.0.4-29] in README.
+    #
+    module Model
+      def self.generate(object_names, target_org: nil)
+        generator = Generator.new(target_org: target_org)
+
+        object_names.each do |object_name|
+          generator.generate(object_name)
+        end
+      end
+    end
+  end
+end