active_force 0.27.1 → 0.28.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc1c415b6de1e133528660a416b470d81eee1b8e075f7150ee9244f32d6c9c4c
-  data.tar.gz: c4a24611cdc27f447c0c3b3e29d14c16c5e8c5b701f9cfcdd6f0469b057e5622
+  metadata.gz: 9282bb2814d5d90acdad820f72977aee58dfa17af2feff228e05a68c77b1cece
+  data.tar.gz: 34e234b1cf52121f65853f9fea12c438b344a800f5d3623931b2d5b45230dd43
 SHA512:
-  metadata.gz: 2de4234e2f417c7fc79c04d2dbbc039399f55fa63ea083a5e4b2b45eaf568d18d66fba3d577928d665a4ff816cb45dd15d0169df1837bc4495b6d8d369ebefe5
-  data.tar.gz: 0d35e111badf4d1226d1a422c586fffe0eaa93fd0c50f54b88b381ba1b062b5460cc035e6989baf15583cae916e42c4e2042fce433fb95bfae0db0ebe0ea2c1d
+  metadata.gz: e056683a3151f3528e3ee1d5bae676ae6f0366ce4fdf4af718b28366c8fbd2114401860fe781fddff0722b40db97ca16f1560eac34e5bb9b5f9cad72a74311e3
+  data.tar.gz: ca35e7aacf091512287c65e4a7e816f0fe1eb027716dd67d498b6fe4c9c8d6a4156b2b54898e9c1b90d48b7b8e8abb095eecaa4f140b6777a0905ad88093b9fc

data/.claude/skills/release/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: release
+description: Release a new version of the active_force gem. Use when asked to cut, prepare, or publish a release. Phase 1 (default) prepares the release PR; phase 2 (`publish`, after the PR is merged) builds and pushes the gem and creates the GitHub release.
+argument-hint: "[version|publish] [--dry-run]"
+---
+
+# Releasing active_force
+
+Two phases, split by the release PR being reviewed and merged. The argument is either a version or `publish`, never both.
+
+- A version (`0.28.0`, no `v`) runs phase 1 with that version.
+- No argument runs phase 1 and follows "Choosing the version" below.
+- `publish` runs phase 2. It takes no version: it reads `VERSION` from `lib/active_force/version.rb` on an up-to-date `main`, which is the merged release.
+
+`--dry-run` can be added to either form. See "Dry run" below.
+
+## Dry run
+
+With `--dry-run`, work through the phase as written but change nothing: describe what each step would do, with the real values filled in, and stop at the end. Print the plan as a numbered list in the same order as the steps, marking each as `would do`, `would skip (already done)` or `blocked (reason)`.
+
+Only these commands are allowed:
+- Read-only git: `git status`, `git fetch`, `git log`, `git diff`, `git show origin/main:<path>`, `git ls-remote --tags origin <tag>`. Do not switch branches or pull; read `main` through `origin/main` instead.
+- Read-only GitHub: `gh pr list`, `gh pr view`, `gh release list`, `gh release view`, and the `generate-notes` API call (it only returns text).
+- `gem list -r`.
+
+Do not run `git switch`, `git pull`, `git commit`, `git push`, `gem build`, `gem push`, `gh pr create`, `gh release create`, or edit any file. If no version was given, still propose one and ask for it: the plan depends on it. Do not ask for the confirmations that precede `gem push` or `gh release create`; show what you would ask instead.
+
+What to show:
+- **Phase 1:** the chosen version, the branch name, the PR title, the exact `CHANGELOG.md` diff and `version.rb` change as they would be written, any `TBD` links, and the result of the already-released check.
+- **Phase 2:** the version read from `origin/main`, whether the release PR is merged (and its number), the already-done check for rubygems, the GitHub release and the tag, the commands that would build and push, and the **final release notes** with the release PR's bullet removed.
+
+End by saying nothing was changed, and that running the same command without `--dry-run` would do it for real.
+
+## Choosing the version
+
+Read the `## Not released` section of `CHANGELOG.md` and the current `ActiveForce::VERSION` in `lib/active_force/version.rb`.
+
+- If there are no entries under `Not released`, stop and say there is nothing to release.
+- Otherwise propose a bump (new feature or behavior change = minor, fixes only = patch, breaking change = major; this gem is 0.x so breaking changes are also a minor bump) with a one-line reason, and **ask the user to confirm or give a different version**. Never pick one silently.
+
+## Phase 1: prepare the release PR
+
+1. Require no modified or staged tracked files (`git status --untracked-files=no` is empty); untracked files don't matter. `git switch main && git pull`.
+2. Check the `Not released` entries for placeholder links (`pull/TBD`). If any are found, list them and ask the user before continuing.
+3. Refuse if `{version}` is already released: a git tag `{version}` exists, or `gem list -r -e active_force --all` includes it. `{version}` must also be greater than the current `VERSION`.
+4. `git switch -c release_{version}`.
+5. Set `VERSION = '{version}'` in `lib/active_force/version.rb`.
+6. In `CHANGELOG.md`, insert a new `## {version}` heading directly under `## Not released`, so the existing entries fall under it, and leave `## Not released` at the top, empty. Result:
+
+   ```
+   # Changelog
+
+   ## Not released
+
+   ## {version}
+   - ...entries...
+   ```
+7. Do not touch `Gemfile.lock` (gitignored) and never `git add` `*.gem` files. Stage only `version.rb` and `CHANGELOG.md`.
+8. Commit as `Release {version}`, push, and open a PR titled `Release {version}`. **Do not use the Linear `KEY-N | TYPE | title` format for release PRs.** The body can be the changelog entries being released.
+9. Report the PR URL and stop. Someone else approves and merges it. Do not merge it.
+
+## Phase 2: publish (only after the release PR is merged)
+
+Naming, matching past releases: the git tag is `{version}` (no `v`) and the GitHub release title is `v{version}`.
+
+1. `git switch main && git pull`. Read `{version}` from `version.rb`.
+2. Confirm the release PR is merged: `gh pr list --head release_{version} --state merged --json number,title`. If it isn't, stop and say so. This works after the branch is deleted. Keep the PR number for step 6.
+3. **Check what is already done**, so a rerun resumes instead of failing partway. Report the result to the user, skip the steps that are done, and continue with the rest:
+   - On rubygems: `gem list -r -e active_force --all` includes `{version}` -> skip build and push (steps 4-5).
+   - GitHub release: `gh release view {version}` succeeds -> skip notes and release (steps 6-7). If it succeeds, tell the user the release already exists and give the link.
+   - A tag `{version}` exists (`git ls-remote --tags origin {version}`) with no GitHub release: stop and ask the user. The tag may point at the wrong commit, so don't create a release on it unprompted.
+   - If everything is done, say so and stop.
+4. `gem build active_force.gemspec`.
+5. **Ask for explicit confirmation, then** `gem push active_force-{version}.gem`. A push cannot be undone. If rubygems needs an MFA code, ask the user to run it themselves with `! gem push active_force-{version}.gem`.
+6. Generate release notes and drop the release PR's own entry:
+
+   ```
+   gh api repos/{owner}/{repo}/releases/generate-notes \
+     -f tag_name={version} -f previous_tag_name={previous_tag} -f target_commitish=main \
+     --jq .body
+   ```
+
+   `{previous_tag}` is `gh release list --limit 1 --json tagName --jq '.[0].tagName'`. Remove the bullet that links to the release PR's number (from step 2); do not match on its title. Keep everything else, including the "Full Changelog" line.
+7. Show the user the final notes and ask to confirm. Then:
+
+   ```
+   gh release create {version} --target main --title "v{version}" --notes-file <file>
+   ```
+
+   This creates the tag.
+8. Report the rubygems and GitHub release links. Leave the built `.gem` file alone (gitignored).

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Not released
 
+## 0.28.1
+- `modified_attributes` computes the changed attribute names once instead of once per attribute, making it linear in the number of fields. The result is unchanged. (https://github.com/Beyond-Finance/active_force/pull/126)
+
+## 0.28.0
+- Add `delete` / `delete_all` (class, relation and instance) using the Composite sObject Collections API. Ids are deleted in chunks of 200, each chunk all-or-none, and the first failing chunk raises `ActiveForce::DeleteFailed` with the Salesforce `errors` and the `deleted_count` from earlier chunks, which stay deleted. Nothing is retried, and ids that are already deleted or never existed are errors like any other. (https://github.com/Beyond-Finance/active_force/pull/119)
+- `delete` raises `ArgumentError` before sending any request when an id's key prefix belongs to another object, so `Account.delete(a_contact_id)` no longer deletes the Contact. The prefix comes from `Model.key_prefix`, read from describe once per class and cached. Objects with no key prefix are not checked, and objects that share a prefix (`ContentDocument` and `ContentNote`) can still be mixed up. (https://github.com/Beyond-Finance/active_force/pull/122)
+- `delete_all` raises `ActiveForce::UnscopedDelete` before querying anything when the query has no `where` condition, so `Account.delete_all` can no longer delete every record of an object. Unlike ActiveRecord, `delete_all` is reserved for scoped queries. (https://github.com/Beyond-Finance/active_force/pull/123)
+
 ## 0.27.1
 - `find` and `find!` quote the id the same way `where` quotes string values. The SOQL does not change for ids without `'` or `\`. (https://github.com/Beyond-Finance/active_force/pull/TBD)
 

data/README.md

@@ -271,6 +271,48 @@ accounts = Account.where(web_enabled: 1).limit(2)
 with data from another API, and will only query the other API once.
 ```
 
+### Deleting
+
+```ruby
+Account.find('001...').destroy        # runs :destroy callbacks, one API call
+Account.find('001...').delete         # no callbacks
+
+Account.delete('001...')              #=> 1
+Account.delete(['001...', '002...'])  #=> 2
+Account.where(web_enable: false).delete_all  #=> number of records deleted
+Account.delete_all                    # raises ActiveForce::UnscopedDelete
+```
+
+`delete` and `delete_all` skip callbacks and return the number of records deleted. An id that no
+longer exists, or never existed, raises `ActiveForce::DeleteFailed`.
+
+Unlike ActiveRecord, `delete_all` needs a `where` condition: on an unfiltered query, including
+`Account.delete_all` and `Account.where(nil).delete_all`, it raises `ActiveForce::UnscopedDelete` before
+querying anything. `limit`, `order` and `offset` are not filters. This guards against deleting
+every record in an object by accident, but it can't tell that a condition such as `where("1=1")`
+matches everything. `Account.delete(ids)` takes an explicit list and is unaffected.
+
+The endpoint takes ids only, so it can't tell which object an id belongs to. To guard against
+deleting the wrong record, `Model.delete` compares each id's 3-character key prefix with the
+model's (`Model.key_prefix`, read from Salesforce's describe once per class and cached) and
+raises `ArgumentError` before sending anything if one doesn't match. `Account.delete(a_contact_id)`
+raises. Objects with no key prefix, such as history objects, are not checked. A few objects share a
+prefix (`ContentDocument` and `ContentNote`), so ids of those can still be mixed up.
+
+They use the REST Composite sObject Collections endpoint, at most 200 ids per request, so
+`delete_all` on 1,000 records makes about 5 API calls. Each request is sent with `allOrNone`, so
+it deletes all of its records or none of them.
+
+ActiveRecord runs `delete_all` as a single atomic statement. Salesforce can only offer that within
+one request, so a call with more than 200 ids is not atomic as a whole. ActiveForce does not retry
+or work around failures: the first request that fails raises `ActiveForce::DeleteFailed` and the
+remaining requests are not sent. It carries `errors` (the Salesforce error details, each with its
+record `id`) and `deleted_count` (records removed by earlier requests, which stay deleted). Calls
+with 200 ids or fewer are fully atomic. That includes an id that no longer exists, which is an
+error like any other and rolls back its request, so the caller decides how to handle it.
+
+For large asynchronous deletes, see [Bulk Jobs](#bulk-jobs).
+
 ### Bulk Jobs
 
 For more information about usage and limits of the Salesforce Bulk API see the [docs][4].

data/active_force.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'activemodel', '>= 7.0'
   spec.add_dependency 'activesupport', '>= 7.0'
+  spec.add_dependency 'csv'
   spec.add_dependency 'restforce',   '>= 5'
   spec.add_development_dependency 'rake', '>= 0'
   spec.add_development_dependency 'rspec', '>= 0'

data/lib/active_force/active_query.rb

@@ -24,6 +24,9 @@ module ActiveForce
     end
   end
 
+  # Raised by delete_all on a query with no filter conditions.
+  class UnscopedDelete < ArgumentError; end
+
   class ActiveQuery < Query
     extend Forwardable
 
@@ -92,7 +95,7 @@ module ActiveForce
         fields_collection = ActiveForce::SelectBuilder.new(selected_fields, self).parse
         nested_query_fields.concat(fields_collection[:nested_query_fields]) if fields_collection[:nested_query_fields]
         return self if fields_collection[:non_nested_query_fields].blank?
-  
+
         super *fields_collection[:non_nested_query_fields]
       end
     end
@@ -101,6 +104,12 @@ module ActiveForce
       super.pluck(:id)
     end
 
+    def delete_all
+      raise UnscopedDelete, "delete_all requires a where condition on #{table_name}" unless filtered?
+
+      sobject.delete(ids)
+    end
+
     def find!(id)
       result = find(id)
       raise RecordNotFound.new("Couldn't find #{table_name} with id #{id}", table_name, id: id) if result.nil?
@@ -120,7 +129,7 @@ module ActiveForce
     end
 
     def includes(*relations)
-      includes_query = Association::EagerLoadBuilderForNestedIncludes.build(relations, sobject, nil, nested_query_fields) 
+      includes_query = Association::EagerLoadBuilderForNestedIncludes.build(relations, sobject, nil, nested_query_fields)
       fields includes_query[:fields]
       association_mapping.merge!(includes_query[:association_mapping])
       self

data/lib/active_force/composite_collection_delete.rb

@@ -0,0 +1,73 @@
+require 'active_support/all'
+
+module ActiveForce
+  # Raised when Salesforce rejects a delete. +errors+ holds the failing
+  # per-record results and +deleted_count+ the records removed by earlier
+  # chunks of the same call, which stay deleted.
+  class DeleteFailed < StandardError
+    attr_reader :errors, :deleted_count
+
+    def initialize(errors, deleted_count)
+      @errors = errors
+      @deleted_count = deleted_count
+
+      super("Delete failed after deleting #{deleted_count} record(s): #{errors.to_json}")
+    end
+  end
+
+  # Deletes records through the Composite sObject Collections endpoint
+  # (DELETE /composite/sobjects). Salesforce accepts at most 200 ids per request,
+  # so ids are sent in chunks of 200. Each chunk is all-or-none and chunks are
+  # independent of each other. The first chunk with a failing record raises
+  # DeleteFailed and the remaining chunks are not sent; nothing is retried or
+  # worked around, including ids that are already deleted or never existed.
+  class CompositeCollectionDelete
+    CHUNK_SIZE = 200
+    ROLLED_BACK = 'ALL_OR_NONE_OPERATION_ROLLED_BACK'.freeze
+
+    def self.call(ids, sfdc_client = ActiveForce.sfdc_client)
+      new(ids, sfdc_client).call
+    end
+
+    attr_reader :ids, :sfdc_client, :deleted_count
+
+    def initialize(ids, sfdc_client)
+      @ids = Array(ids).flatten.reject(&:blank?).uniq
+      @sfdc_client = sfdc_client
+      @deleted_count = 0
+    end
+
+    # Returns the number of records deleted.
+    def call
+      ids.each_slice(CHUNK_SIZE) { |chunk| delete_chunk(chunk) }
+      deleted_count
+    end
+
+    private
+
+    def delete_chunk(chunk)
+      failures = chunk.zip(request(chunk)).reject { |_, result| result['success'] }
+      raise DeleteFailed.new(errors_for(failures), deleted_count) if failures.any?
+
+      @deleted_count += chunk.size
+    end
+
+    def request(chunk)
+      sfdc_client.api_delete('composite/sobjects', ids: chunk.join(','), allOrNone: true).body
+    end
+
+    # Reports the records that failed for a reason of their own. Records only
+    # rolled back because another one failed are left out, unless nothing else
+    # explains the failure.
+    def errors_for(failures)
+      causes = failures.reject { |_, result| rolled_back?(result) }
+      (causes.presence || failures).flat_map do |id, result|
+        result['errors'].map { |error| error.to_h.merge('id' => id) }
+      end
+    end
+
+    def rolled_back?(result)
+      result['errors'].map { |error| error['statusCode'] } == [ROLLED_BACK]
+    end
+  end
+end

data/lib/active_force/query.rb

@@ -111,6 +111,10 @@ module ActiveForce
       clone_and_set_instance_variables(query_fields: ["Id"])
     end
 
+    def filtered?
+      @conditions.any?(&:present?)
+    end
+
     protected
       def quote_string(s)
         "'#{s.gsub(/(['\\])/, '\\\\\\1')}'"

data/lib/active_force/sobject.rb

@@ -2,6 +2,7 @@ require 'active_model'
 require 'active_force/active_query'
 require 'active_force/association'
 require 'active_force/bulk'
+require 'active_force/composite_collection_delete'
 require 'active_force/mapping'
 require 'yaml'
 require 'forwardable'
@@ -32,10 +33,22 @@ module ActiveForce
 
     class << self
       extend Forwardable
-      def_delegators :query, :not, :or, :where, :first, :last, :all, :find, :find!, :find_by, :find_by!, :sum, :count, :includes, :limit, :order, :select, :none
+      def_delegators :query, :not, :or, :where, :first, :last, :all, :find, :find!, :find_by, :find_by!, :sum, :count, :includes, :limit, :order, :select, :none, :delete_all
       def_delegators :mapping, :table, :custom_table?, :mappings
       alias_method :table_name=, :table_name_store=
 
+      def delete(id_or_ids)
+        ids = Array(id_or_ids)
+        ensure_ids_belong_to_this_object!(ids)
+        CompositeCollectionDelete.call(ids, sfdc_client)
+      end
+
+      def key_prefix
+        return @key_prefix if defined?(@key_prefix)
+
+        @key_prefix = describe['keyPrefix'].presence
+      end
+
       def update(id, attributes)
         prepare_for_update(id, attributes).update
       end
@@ -50,6 +63,17 @@ module ActiveForce
 
       private
 
+      def ensure_ids_belong_to_this_object!(ids)
+        ids = ids.reject(&:blank?)
+        return if ids.empty? || key_prefix.nil?
+
+        foreign = ids.reject { |id| id.to_s.start_with?(key_prefix) }
+        return if foreign.empty?
+
+        raise ArgumentError, "Cannot delete #{foreign.first(5).join(', ')} through #{name}: " \
+                             "#{table_name} ids start with #{key_prefix}"
+      end
+
       def prepare_for_update(id, attributes)
         new(attributes.merge(id: id)).tap do |obj|
           attributes.each do |name, value|
@@ -163,6 +187,11 @@ module ActiveForce
       end
     end
 
+    def delete
+      self.class.delete(id)
+      self
+    end
+
     def self.create args
       new(args).create
     end
@@ -204,7 +233,7 @@ module ActiveForce
     end
 
     def modified_attributes
-      attributes.select{ |attr, key| changed.include? attr.to_s }
+      attributes.slice(*changed)
     end
 
     def reload

data/lib/active_force/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveForce
-  VERSION = '0.27.1'
+  VERSION = '0.28.1'
 end

data/spec/active_force/active_query_spec.rb

@@ -444,7 +444,7 @@ describe ActiveForce::ActiveQuery do
     it 'raises if record not found' do
       allow(client).to receive(:query).and_return(build_restforce_collection)
       expect { active_query.find_by!(field: 123) }
-        .to raise_error(ActiveForce::RecordNotFound, "Couldn't find #{sobject.table_name} with {:field=>123}")
+        .to raise_error(ActiveForce::RecordNotFound, "Couldn't find #{sobject.table_name} with #{{ field: 123 }}")
     end
 
     it 'should raise UnknownFieldError if given invalid field' do
@@ -634,4 +634,44 @@ describe ActiveForce::ActiveQuery do
       expect(active_query.ids).to eq api_result.map { |r| r['Id'] }
     end
   end
+
+  describe "#delete_all" do
+    before do
+      allow(client).to receive(:query).and_return(api_result)
+      api_result.each do |instance|
+        allow(active_query).to receive(:build).with(instance, {}).and_return(build_restforce_sobject(id: instance['Id']))
+      end
+    end
+
+    it "deletes the ids matched by the query and returns the count" do
+      expect(sobject).to receive(:delete).with(%w[0000000000AAAAABBB 0000000000CCCCCDDD]).and_return(2)
+      expect(active_query.where(field: 'x').delete_all).to eq 2
+    end
+
+    it "does not delete anything when nothing matches" do
+      allow(client).to receive(:query).and_return([])
+      expect(sobject).to receive(:delete).with([]).and_return(0)
+      expect(active_query.where(field: 'x').delete_all).to eq 0
+    end
+
+    describe "without a where condition" do
+      before { expect(client).not_to receive(:query) }
+
+      it "raises before running any query" do
+        expect(sobject).not_to receive(:delete)
+        expect { active_query.delete_all }
+          .to raise_error(ActiveForce::UnscopedDelete, /delete_all requires a where condition on #{sobject.table_name}/)
+      end
+
+      it "raises for where(nil) and non-filtering modifiers" do
+        [active_query.where(nil), active_query.limit(10), active_query.order(:field)].each do |query|
+          expect { query.delete_all }.to raise_error(ActiveForce::UnscopedDelete)
+        end
+      end
+
+      it "is an ArgumentError" do
+        expect { active_query.delete_all }.to raise_error(ArgumentError)
+      end
+    end
+  end
 end

data/spec/active_force/composite_collection_delete_spec.rb

@@ -0,0 +1,152 @@
+require 'spec_helper'
+
+describe ActiveForce::CompositeCollectionDelete do
+  let(:sfdc_client) { double('Client') }
+
+  def success(id)
+    { 'id' => id, 'success' => true, 'errors' => [] }
+  end
+
+  def failure(id, status_code, message = 'boom')
+    { 'id' => id, 'success' => false, 'errors' => [{ 'statusCode' => status_code, 'message' => message, 'fields' => [] }] }
+  end
+
+  def rolled_back(id)
+    failure(id, 'ALL_OR_NONE_OPERATION_ROLLED_BACK', 'Record rolled back because not all records were valid.')
+  end
+
+  def response(results)
+    double('Response', body: results)
+  end
+
+  describe '.call' do
+    it 'defaults to ActiveForce.sfdc_client' do
+      allow(ActiveForce).to receive(:sfdc_client).and_return(sfdc_client)
+      allow(sfdc_client).to receive(:api_delete).and_return(response([success('001')]))
+
+      described_class.call(['001'])
+
+      expect(sfdc_client).to have_received(:api_delete)
+    end
+  end
+
+  describe '#call' do
+    it 'deletes a single id via the composite sobjects endpoint with allOrNone' do
+      expect(sfdc_client).to receive(:api_delete)
+        .with('composite/sobjects', ids: '001', allOrNone: true)
+        .and_return(response([success('001')]))
+
+      expect(described_class.call(['001'], sfdc_client)).to eq 1
+    end
+
+    it 'sends multiple ids comma separated and returns the count deleted' do
+      expect(sfdc_client).to receive(:api_delete)
+        .with('composite/sobjects', ids: '001,002,003', allOrNone: true)
+        .and_return(response(%w[001 002 003].map { |id| success(id) }))
+
+      expect(described_class.call(%w[001 002 003], sfdc_client)).to eq 3
+    end
+
+    it 'ignores blank and duplicate ids' do
+      expect(sfdc_client).to receive(:api_delete)
+        .with('composite/sobjects', ids: '001,002', allOrNone: true)
+        .and_return(response([success('001'), success('002')]))
+
+      expect(described_class.call(['001', nil, '', '001', '002'], sfdc_client)).to eq 2
+    end
+
+    it 'makes no request and returns 0 when there are no ids' do
+      expect(sfdc_client).not_to receive(:api_delete)
+
+      expect(described_class.call([nil], sfdc_client)).to eq 0
+      expect(described_class.call([], sfdc_client)).to eq 0
+    end
+
+    context 'with more ids than fit in one request' do
+      let(:ids) { (1..450).map { |i| format('%018d', i) } }
+
+      it 'chunks into requests of 200 ids' do
+        sent = []
+        allow(sfdc_client).to receive(:api_delete) do |_path, params|
+          chunk = params[:ids].split(',')
+          sent << chunk
+          response(chunk.map { |id| success(id) })
+        end
+
+        expect(described_class.call(ids, sfdc_client)).to eq 450
+        expect(sent.map(&:size)).to eq [200, 200, 50]
+        expect(sent.flatten).to eq ids
+      end
+    end
+
+    context 'when a record fails' do
+      it 'raises DeleteFailed with the error details and does not retry' do
+        expect(sfdc_client).to receive(:api_delete).once
+          .and_return(response([failure('001', 'DELETE_FAILED', 'has child records'), rolled_back('002')]))
+
+        expect { described_class.call(%w[001 002], sfdc_client) }
+          .to raise_error(ActiveForce::DeleteFailed) { |error|
+            expect(error.deleted_count).to eq 0
+            expect(error.errors).to eq [{ 'id' => '001', 'statusCode' => 'DELETE_FAILED', 'message' => 'has child records', 'fields' => [] }]
+            expect(error.message).to include('DELETE_FAILED', 'has child records')
+          }
+      end
+
+      %w[ENTITY_IS_DELETED INVALID_CROSS_REFERENCE_KEY].each do |code|
+        it "raises for a missing id (#{code}) instead of working around it" do
+          expect(sfdc_client).to receive(:api_delete).once
+            .and_return(response([success('001'), failure('002', code), rolled_back('003')]))
+
+          expect { described_class.call(%w[001 002 003], sfdc_client) }
+            .to raise_error(ActiveForce::DeleteFailed) { |error|
+              expect(error.errors.map { |e| [e['id'], e['statusCode']] }).to eq [['002', code]]
+              expect(error.deleted_count).to eq 0
+            }
+        end
+      end
+
+      it 'reports every record that failed for its own reason' do
+        allow(sfdc_client).to receive(:api_delete)
+          .and_return(response([failure('001', 'ENTITY_IS_DELETED'), failure('002', 'DELETE_FAILED'), rolled_back('003')]))
+
+        expect { described_class.call(%w[001 002 003], sfdc_client) }
+          .to raise_error(ActiveForce::DeleteFailed) { |error| expect(error.errors.map { |e| e['id'] }).to eq %w[001 002] }
+      end
+
+      it 'raises rather than report success when every result was rolled back' do
+        allow(sfdc_client).to receive(:api_delete)
+          .and_return(response([rolled_back('001'), rolled_back('002')]))
+
+        expect { described_class.call(%w[001 002], sfdc_client) }
+          .to raise_error(ActiveForce::DeleteFailed) { |error|
+            expect(error.deleted_count).to eq 0
+            expect(error.errors.map { |e| e['statusCode'] }).to eq %w[ALL_OR_NONE_OPERATION_ROLLED_BACK] * 2
+          }
+      end
+    end
+
+    context 'when a later chunk fails' do
+      let(:ids) { (1..450).map { |i| format('%018d', i) } }
+
+      it 'reports the earlier chunks as deleted and does not send the rest' do
+        sent = []
+        allow(sfdc_client).to receive(:api_delete) do |_path, params|
+          chunk = params[:ids].split(',')
+          sent << chunk
+          if sent.size == 1
+            response(chunk.map { |id| success(id) })
+          else
+            response(chunk.map { |id| id == chunk.first ? failure(id, 'DELETE_FAILED') : rolled_back(id) })
+          end
+        end
+
+        expect { described_class.call(ids, sfdc_client) }
+          .to raise_error(ActiveForce::DeleteFailed) { |error|
+            expect(error.deleted_count).to eq 200
+            expect(error.errors.map { |e| e['id'] }).to eq [ids[200]]
+            expect(sent.size).to eq 2
+          }
+      end
+    end
+  end
+end

data/spec/active_force/query_spec.rb

@@ -269,4 +269,27 @@ describe ActiveForce::Query do
       expect(query.where("name = 'cool'").ids.to_s).to eq "SELECT Id FROM table_name WHERE (name = 'cool')"
     end
   end
+
+  describe ".filtered?" do
+    it "is false without conditions" do
+      expect(query.filtered?).to be false
+      expect(query.all.filtered?).to be false
+    end
+
+    it "is false for limit, order and offset" do
+      expect(query.limit(5).order('name').offset(2).filtered?).to be false
+    end
+
+    it "is false for a blank condition" do
+      expect(query.where('').filtered?).to be false
+    end
+
+    it "is true once a condition is added" do
+      expect(query.where("name = 'x'").filtered?).to be true
+    end
+
+    it "is true after or" do
+      expect(query.where("name = 'x'").or(query.where("name = 'y'")).filtered?).to be true
+    end
+  end
 end

data/spec/active_force/sobject_spec.rb

@@ -302,6 +302,21 @@ describe ActiveForce::SObject do
       end
     end
 
+    describe "#delete" do
+      before { allow(Whizbang).to receive(:key_prefix).and_return(nil) }
+
+      it "deletes by id without running callbacks and returns itself" do
+        expect(ActiveForce::CompositeCollectionDelete).to receive(:call).with(['1'], client).and_return(1)
+        expect(instance).not_to receive(:run_callbacks)
+        expect(instance.delete).to eq instance
+      end
+
+      it "does not call the API for a record without an id" do
+        expect(client).not_to receive(:api_delete)
+        Whizbang.new.delete
+      end
+    end
+
     describe 'self.create' do
       before do
         expect(client).to receive(:create!)
@@ -532,6 +547,116 @@ describe ActiveForce::SObject do
     end
   end
 
+  describe '#modified_attributes' do
+    context 'with a new instance' do
+      it 'returns an empty hash when nothing has been assigned' do
+        expect(Whizbang.new.modified_attributes).to eq({})
+      end
+
+      it 'returns only the assigned attributes' do
+        instance = Whizbang.new(text: 'some text', boolean: false)
+
+        expect(instance.modified_attributes).to eq('text' => 'some text', 'boolean' => false)
+      end
+
+      it 'returns the cast values of the assigned attributes' do
+        instance = Whizbang.new(date: '2010-01-01', percent: '21')
+
+        expect(instance.modified_attributes).to eq('date' => Date.new(2010, 1, 1), 'percent' => 21.0)
+      end
+    end
+
+    context 'with a built instance' do
+      let(:instance) { Whizbang.build sobject_hash }
+
+      it 'returns an empty hash when nothing has changed' do
+        expect(instance.modified_attributes).to eq({})
+      end
+
+      it 'returns only the changed attributes with their new values' do
+        instance.text = 'changed text'
+        instance.checkbox = true
+
+        expect(instance.modified_attributes).to eq('checkbox' => true, 'text' => 'changed text')
+      end
+
+      it 'excludes attributes assigned their current value' do
+        instance.text = 'Hi there!'
+        instance.percent = 21
+
+        expect(instance.modified_attributes).to eq({})
+      end
+
+      it 'excludes attributes changed and then restored to their original value' do
+        instance.text = 'changed text'
+        instance.text = 'Hi there!'
+
+        expect(instance.modified_attributes).to eq({})
+      end
+
+      it 'includes attributes changed to nil' do
+        instance.text = nil
+
+        expect(instance.modified_attributes).to eq('text' => nil)
+      end
+
+      it 'includes attributes mutated in place' do
+        instance.text << ' Bye!'
+
+        expect(instance.modified_attributes).to eq('text' => 'Hi there! Bye!')
+      end
+
+      it 'excludes attributes that were not selected' do
+        expect(Whizbang.attribute_names).to include('estimated_close_date', 'updated_from')
+        expect(instance.modified_attributes.keys).not_to include('estimated_close_date', 'updated_from')
+      end
+
+      it 'includes an unselected attribute once it is assigned' do
+        instance.updated_from = 'Rails'
+
+        expect(instance.modified_attributes).to eq('updated_from' => 'Rails')
+      end
+
+      it 'returns string keys in attribute declaration order' do
+        instance.percent = 42
+        instance.text = 'changed text'
+        instance.checkbox = true
+
+        expect(instance.modified_attributes.keys).to eq(%w[checkbox text percent])
+      end
+    end
+
+    context 'after persisting changes' do
+      let(:instance) { Territory.new(id: '1') }
+
+      it 'returns an empty hash after create' do
+        new_instance = Territory.new(name: 'Walter')
+        allow(client).to receive(:create!).and_return('1')
+
+        new_instance.create!
+
+        expect(new_instance.modified_attributes).to eq({})
+      end
+
+      it 'returns an empty hash after update' do
+        allow(client).to receive(:update!).and_return(true)
+
+        instance.update!(name: 'Walter')
+
+        expect(instance.modified_attributes).to eq({})
+      end
+
+      it 'returns an empty hash after reload' do
+        allow(client).to receive(:query).and_return([Restforce::Mash.new(Id: '1', Name: 'Jeff')])
+        instance.name = 'Walter'
+
+        instance.reload
+
+        expect(instance.modified_attributes).to eq({})
+      end
+    end
+  end
+
   describe 'logger output' do
     let(:instance){ Whizbang.new }
 
@@ -661,4 +786,77 @@ describe ActiveForce::SObject do
       end
     end
   end
+
+  describe ".key_prefix" do
+    after { Whizbang.remove_instance_variable(:@key_prefix) if Whizbang.instance_variable_defined?(:@key_prefix) }
+
+    it "reads the keyPrefix from describe" do
+      allow(client).to receive(:describe).with('Whizbang__c').and_return('keyPrefix' => 'a0X')
+      expect(Whizbang.key_prefix).to eq 'a0X'
+    end
+
+    it "describes once per class" do
+      expect(client).to receive(:describe).once.and_return('keyPrefix' => 'a0X')
+      2.times { Whizbang.key_prefix }
+    end
+
+    it "caches a missing prefix as nil without describing again" do
+      expect(client).to receive(:describe).once.and_return('keyPrefix' => nil)
+      2.times { expect(Whizbang.key_prefix).to be_nil }
+    end
+  end
+
+  describe ".delete" do
+    before { allow(Whizbang).to receive(:key_prefix).and_return('a0X') }
+
+    it "deletes a single id and returns the count" do
+      expect(ActiveForce::CompositeCollectionDelete).to receive(:call).with(['a0X1'], client).and_return(1)
+      expect(Whizbang.delete('a0X1')).to eq 1
+    end
+
+    it "deletes an array of ids" do
+      expect(ActiveForce::CompositeCollectionDelete).to receive(:call).with(%w[a0X1 a0X2], client).and_return(2)
+      expect(Whizbang.delete(%w[a0X1 a0X2])).to eq 2
+    end
+
+    it "accepts 15 and 18 character ids with the right prefix" do
+      ids = %w[a0X000000000001 a0X000000000002AAA]
+      expect(ActiveForce::CompositeCollectionDelete).to receive(:call).with(ids, client).and_return(2)
+      expect(Whizbang.delete(ids)).to eq 2
+    end
+
+    it "raises before any request when an id belongs to another object" do
+      expect(ActiveForce::CompositeCollectionDelete).not_to receive(:call)
+      expect { Whizbang.delete(%w[a0X000000000001AAA 003000000000001AAA]) }
+        .to raise_error(ArgumentError, /003000000000001AAA.*Whizbang__c ids start with a0X/)
+    end
+
+    it "does not describe when there are no ids" do
+      allow(Whizbang).to receive(:key_prefix).and_call_original
+      expect(client).not_to receive(:describe)
+      expect(Whizbang.delete([nil, ''])).to eq 0
+    end
+
+    it "skips the check when the object has no key prefix" do
+      allow(Whizbang).to receive(:key_prefix).and_return(nil)
+      expect(ActiveForce::CompositeCollectionDelete).to receive(:call).with(['003000000000001AAA'], client).and_return(1)
+      expect(Whizbang.delete('003000000000001AAA')).to eq 1
+    end
+  end
+
+  describe ".delete_all" do
+    it "is delegated to the query" do
+      query = instance_double(ActiveForce::ActiveQuery)
+      allow(Whizbang).to receive(:query).and_return(query)
+      expect(query).to receive(:delete_all).and_return(3)
+      expect(Whizbang.delete_all).to eq 3
+    end
+
+    it "refuses an unscoped delete before any request" do
+      expect(client).not_to receive(:query)
+      expect(client).not_to receive(:api_delete)
+      expect { Whizbang.delete_all }.to raise_error(ActiveForce::UnscopedDelete)
+      expect { Whizbang.where(nil).delete_all }.to raise_error(ActiveForce::UnscopedDelete)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_force
 version: !ruby/object:Gem::Version
-  version: 0.27.1
+  version: 0.28.1
 platform: ruby
 authors:
 - Eloy Espinaco
@@ -40,6 +40,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: restforce
   requirement: !ruby/object:Gem::Requirement
@@ -145,6 +159,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".circleci/config.yml"
+- ".claude/skills/release/SKILL.md"
 - ".github/ISSUE_TEMPLATE/bug_report.md"
 - ".github/ISSUE_TEMPLATE/feature_request.md"
 - ".gitignore"
@@ -173,6 +188,7 @@ files:
 - lib/active_force/bulk/job_result.rb
 - lib/active_force/bulk/records.rb
 - lib/active_force/composite_batch_query.rb
+- lib/active_force/composite_collection_delete.rb
 - lib/active_force/field.rb
 - lib/active_force/mapping.rb
 - lib/active_force/query.rb
@@ -196,6 +212,7 @@ files:
 - spec/active_force/bulk_spec.rb
 - spec/active_force/callbacks_spec.rb
 - spec/active_force/composite_batch_query_spec.rb
+- spec/active_force/composite_collection_delete_spec.rb
 - spec/active_force/field_spec.rb
 - spec/active_force/mapping_spec.rb
 - spec/active_force/query_notifications_spec.rb
@@ -247,6 +264,7 @@ test_files:
 - spec/active_force/bulk_spec.rb
 - spec/active_force/callbacks_spec.rb
 - spec/active_force/composite_batch_query_spec.rb
+- spec/active_force/composite_collection_delete_spec.rb
 - spec/active_force/field_spec.rb
 - spec/active_force/mapping_spec.rb
 - spec/active_force/query_notifications_spec.rb