sf_cli 0.0.4 → 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/org/core.rb

@@ -1,4 +1,7 @@
 require_relative '../core/base'
+require_relative './login'
+require_relative './display'
+require_relative './list'
 
 module SfCli
   module Sf
@@ -11,50 +14,9 @@ module SfCli
       #
       class Core
         include ::SfCli::Sf::Core::Base
-
-        ConnectionInfo = Struct.new(:id, :access_token, :alias, :instance_url, :user_name, :api_version, :status)
-
-        # login to the org by the browser. (equivalent to *sf* *org* *login* *web*)
-        #
-        # *target_org* --- an alias of paticular org, not default one<br>
-        # *instance_url* --- custom login url.
-        #
-        # == examples:
-        #   sf.org.login_web
-        #   sf.org.login_web target_org: :dev  # if the org you login isn't the default one, you should give it alias name for later use.
-        #
-        # 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_org_commands_unified.htm#cli_reference_org_login_web_unified]
-        #
-        def login_web(target_org: nil, instance_url: nil)
-          flags    = {
-            :"alias"        => target_org,
-            :"instance-url" => instance_url,
-          }
-          action = __method__.to_s.tr('_', ' ')
-          exec(action, flags: flags)
-        end
-
-        #
-        # returns the org's connection information. (equivalent to *sf* *org* *display*)
-        #
-        # *target_org* --- an alias of paticular org, not default one<br>
-        #
-        # 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_org_commands_unified.htm#cli_reference_org_display_unified]
-        #
-        def display(target_org: nil)
-          flags    = {:"target-org" => target_org}
-          json = exec(__method__, flags: flags, redirection: :null_stderr)
-
-          ConnectionInfo.new(
-            id:           json['result']['id'],
-            access_token: json['result']['accessToken'],
-            alias:        json['result']['alias'],
-            instance_url: json['result']['instanceUrl'],
-            user_name:    json['result']['username'],
-            api_version:  json['result']['apiVersion'],
-            status:       json['result']['connectedStatus']
-          )
-        end
+        include Login
+        include Display
+        include List
       end
     end
   end

data/lib/sf_cli/sf/org/display.rb

@@ -0,0 +1,41 @@
+module SfCli::Sf::Org
+  module Display
+    ConnectionInfo = Struct.new(:id, :access_token, :alias, :instance_url, :user_name, :api_version, :status)
+
+    #
+    # returns the org's connection information. (equivalent to *sf* *org* *display*)
+    #
+    # *target_org* --- an alias of paticular org, or username can be used<br>
+    #
+    # ======
+    #  # example (in irb):
+    #
+    #  > sf.org.display
+    #  =>
+    #  #<struct SfCli::Sf::Org::Display::ConnectionInfo
+    #   id="00D5j00000DiuxmEAB",
+    #   access_token="<some access token>",
+    #   alias="dev",
+    #   instance_url="https://hoge-bar-baz.abc.my.salesforce.com.example",
+    #   user_name="user@example.sandbox",
+    #   api_version="61.0",
+    #   status="Connected">
+    #
+    # 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_org_commands_unified.htm#cli_reference_org_display_unified]
+    #
+    def display(target_org: nil)
+      flags    = {:"target-org" => target_org}
+      json = exec(__method__, flags: flags, redirection: :null_stderr)
+
+      ConnectionInfo.new(
+        id:           json['result']['id'],
+        access_token: json['result']['accessToken'],
+        alias:        json['result']['alias'],
+        instance_url: json['result']['instanceUrl'],
+        user_name:    json['result']['username'],
+        api_version:  json['result']['apiVersion'],
+        status:       json['result']['connectedStatus']
+      )
+    end
+  end
+end

data/lib/sf_cli/sf/org/list.rb

@@ -0,0 +1,67 @@
+module SfCli::Sf::Org
+  module List
+    OrgConfig = Struct.new( :accessToken, :instanceUrl, :orgId, :username, :loginUrl,
+      :clientId, :isDevHub, :instanceApiVersion, :instanceApiVersionLastRetrieved, :name,
+      :instanceName, :namespacePrefix, :isSandbox, :isScratch, :trailExpirationDate, :tracksSource,
+      :alias, :isDefaultDevHubUsername, :isDefaultUsername, :lastUsed, :connectedStatus) do
+      def devhub?
+        isDevHub
+      end
+
+      def sandbox?
+        isSandbox
+      end
+
+      def scratch?
+        isScratch
+      end
+
+      def default?
+        isDefaultUsername
+      end
+
+      def default_devhub?
+        isDefaultDevHubUsername
+      end
+
+      def connected?
+        connectedStatus == 'Connected'
+      end
+    end
+
+    # \List orgs you’ve created or authenticated to
+    #
+    # ======
+    #   org_config_list = sf.org.list # returns a list of OrgConfig
+    #
+    # \OrgConfig object has a org information including security sensitive things such as access token, username and so on.
+    #
+    # It also has some methods to identify its org type:
+    # - devhub?
+    # - sandbox?
+    # - scratch?
+    # - default?
+    # - default_devhub?
+    #
+    # and you can check the org connected like this:
+    #   org_config_list = sf.org.list # returns a list of OrgConfig
+    #   org_config.first.conncected?
+    #
+    # 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_org_commands_unified.htm#cli_reference_org_list_unified]
+    #
+    def list
+      flags = {
+        # reserved for later option addition
+      }
+      json = exec(__method__, flags: flags, redirection: :null_stderr)
+
+      others = json['result']['other'].map{|config| OrgConfig.new(**config)}
+      sandboxes = json['result']['sandboxes'].map{|config| OrgConfig.new(**config)}
+      non_scratch_orgs = json['result']['nonScratchOrgs'].map{|config| OrgConfig.new(**config)}
+      devhubs = json['result']['devHubs'].map{|config| OrgConfig.new(**config)}
+      scratch_orgs = json['result']['scratchOrgs'].map{|config| OrgConfig.new(**config)}
+      
+      (others + sandboxes + non_scratch_orgs + devhubs + scratch_orgs).uniq{|config| config.alias}
+    end
+  end
+end