chartmogul-ruby 4.14.0 → 4.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61fce0fe848312e4a28d7cc9cf5baf8bf62bf7a92da434789bfbffa3099c78ef
-  data.tar.gz: 26ab5587c9a0d6c4dc543aca4ff558d4bbe9a89d3e309642c0b933cae2f81433
+  metadata.gz: 1d40707d3a05b63c0ecadcd2a871c769840ebe77182aae281e024167b6f73337
+  data.tar.gz: 89ce86fbbeacdaa4236d00c5a4c2d24926ece3fb1c71b4504b10a6efd1a55f95
 SHA512:
-  metadata.gz: b28f66fa79c6ac41497911e0a2811ce4e419c7ec9a143d0acc8adbe85c5ef21ec71c87533855cf5cf119f0a3fdef519ca1717e0f4cc712c258ac35b363f7dd19
-  data.tar.gz: b6ce9397538e1d1cad6c799e697c4ee4d0a33b2de8d31d628bc6cfe9d34e1902f2f5257ecf343ca4e316cb828e8c4615e1208dc3bb25ce5265716c7c50131f08
+  metadata.gz: 77f1fd6beaea8d60c4b4eb2a83a10fadb39ad67886a8a893340644de2864a56900e598a99a97b81b6700c465b8a201d320b5406b73bf86e470307fa80d771cde
+  data.tar.gz: f34020017620ea6d47992fef1a74db9863929cc98c6ebf3fc5f57206779de1e4f756ab39402af88704b39077873f878336dafc0bc677f48f7157023e1b36923f

data/lib/chartmogul/api/actions/update.rb

@@ -16,7 +16,8 @@ module ChartMogul
             end
           end
 
-          json = ChartMogul::Utils::JSONParser.parse(resp.body, immutable_keys: self.class.immutable_keys)
+          parsed_body = resp.body.empty? ? '{}' : resp.body
+          json = ChartMogul::Utils::JSONParser.parse(parsed_body, immutable_keys: self.class.immutable_keys)
 
           assign_all_attributes(json)
         end
@@ -31,7 +32,8 @@ module ChartMogul
                 req.body = JSON.dump(resource.serialize_for_write)
               end
             end
-            json = ChartMogul::Utils::JSONParser.parse(resp.body, immutable_keys: immutable_keys)
+            parsed_body = resp.body.empty? ? '{}' : resp.body
+            json = ChartMogul::Utils::JSONParser.parse(parsed_body, immutable_keys: immutable_keys)
 
             new_from_json(json)
           end

data/lib/chartmogul/contact.rb

@@ -7,6 +7,7 @@ module ChartMogul
     set_immutable_keys([:custom])
 
     readonly_attr :uuid
+    readonly_attr :historical_values
 
     writeable_attr :customer_uuid
     writeable_attr :data_source_uuid
@@ -20,8 +21,10 @@ module ChartMogul
     writeable_attr :linked_in
     writeable_attr :twitter
     writeable_attr :notes
+    writeable_attr :last_seen
     writeable_attr :external_id
     writeable_attr :custom
+    writeable_attr :overrides
 
     include API::Actions::Create
     include API::Actions::Custom
@@ -38,6 +41,22 @@ module ChartMogul
       true
     end
 
+    def tasks(options = {})
+      Tasks.all(options.merge(contact_uuid: uuid))
+    end
+
+    def create_task(options = {})
+      Task.create!(with_associated_object_identifier(options))
+    end
+
+    def entity_notes(options = {})
+      EntityNotes.all(options.merge(contact_uuid: uuid))
+    end
+
+    def create_entity_note(options = {})
+      EntityNote.create!(with_associated_object_identifier(options))
+    end
+
     def serialize_for_write
       super.tap do |attributes|
         attributes.clone.each do |attribute_name, attribute_value|
@@ -55,6 +74,42 @@ module ChartMogul
         attributes[:external_id] = nil if instance_variable_defined?(:@external_id) && external_id.nil?
       end
     end
+
+    # Responses echo the current override state, so only overrides assigned by
+    # the caller are serialized: replaying an echoed `true` flag on a later
+    # update! would re-protect stale in-memory values on the server. The echoed
+    # hash is deep-frozen and `dup` copies only the top level — request changes
+    # by assigning a freshly built hash, not by editing or duplicating the
+    # reader's result. Assigned intent is cleared by the response
+    # of the successful write (every write endpoint echoes `overrides`); an
+    # endpoint that stopped echoing would leave it set and resend it on the
+    # next update!.
+    def overrides=(value)
+      @overrides_requested = true
+      @overrides = value
+    end
+
+    def serialize_overrides
+      overrides if @overrides_requested
+    end
+
+    private
+
+    def set_overrides(value)
+      @overrides_requested = false
+      @overrides = freeze_nested(value)
+    end
+
+    def freeze_nested(value)
+      value.each_value { |nested| freeze_nested(nested) } if value.is_a?(Hash)
+      value.freeze
+    end
+
+    def with_associated_object_identifier(options)
+      return options if options[:customer_uuid] || options[:associated_object_identifier]
+
+      options.merge(associated_object_identifier: { associated_object: 'contact', method: 'uuid', value: uuid })
+    end
   end
 
   class Contacts < APIResource

data/lib/chartmogul/customer.rb

@@ -5,7 +5,7 @@ module ChartMogul
   class Customer < APIResource
     set_resource_name 'Customer'
     set_resource_path '/v1/customers'
-    set_immutable_keys(%i[attributes custom])
+    set_immutable_keys(%i[attributes custom overrides historical_values])
 
     readonly_attr :uuid
     readonly_attr :id
@@ -22,6 +22,7 @@ module ChartMogul
     readonly_attr :currency_sign
     readonly_attr :data_source_uuids
     readonly_attr :external_ids
+    readonly_attr :historical_values
 
     writeable_attr :attributes
     writeable_attr :external_id
@@ -38,6 +39,7 @@ module ChartMogul
     writeable_attr :owner
     writeable_attr :primary_contact
     writeable_attr :website_url
+    writeable_attr :overrides
 
     include API::Actions::Create
     include API::Actions::Custom
@@ -57,16 +59,20 @@ module ChartMogul
       all(external_id: external_id).first
     end
 
-    def self.retrieve_attributes(customer_uuid)
-      custom_without_assign!(:get, "/v1/customers/#{customer_uuid}/attributes")
+    def self.retrieve_attributes(customer_uuid, options = {})
+      path = ChartMogul::ResourcePath.new("/v1/customers/#{customer_uuid}/attributes")
+      custom_without_assign!(:get, path.apply_with_get_params(options))
     end
 
     def self.add_tags_by_email!(email, *tags)
       custom_without_assign!(:post, '/v1/customers/attributes/tags', email: email, tags: tags)
     end
 
-    def self.add_custom_attributes_by_email!(email, *custom_attrs)
-      custom_without_assign!(:post, '/v1/customers/attributes/custom', email: email, custom: custom_attrs)
+    def self.add_custom_attributes_by_email!(email, *custom_attrs, overrides: nil, **brace_less_attr)
+      custom_attrs << brace_less_attr unless brace_less_attr.empty?
+      body = { email: email, custom: custom_attrs }
+      body[:overrides] = overrides if overrides
+      custom_without_assign!(:post, '/v1/customers/attributes/custom', body)
     end
 
     def self.merge!(into_uuid:, from_uuid:)
@@ -109,14 +115,26 @@ module ChartMogul
       Contact.create!(options.merge(customer_uuid: uuid))
     end
 
+    # @deprecated Use {#entity_notes} instead.
     def notes(options = {})
+      warn 'DEPRECATION WARNING: the method ChartMogul::Customer#notes is deprecated. Use ChartMogul::Customer#entity_notes instead.'
       Notes.all(options.merge(customer_uuid: uuid))
     end
 
+    # @deprecated Use {#create_entity_note} instead.
     def create_note(options = {})
+      warn 'DEPRECATION WARNING: the method ChartMogul::Customer#create_note is deprecated. Use ChartMogul::Customer#create_entity_note instead.'
       Note.create!(options.merge(customer_uuid: uuid))
     end
 
+    def entity_notes(options = {})
+      EntityNotes.all(options.merge(customer_uuid: uuid))
+    end
+
+    def create_entity_note(options = {})
+      EntityNote.create!(options.merge(customer_uuid: uuid))
+    end
+
     def opportunities(options = {})
       Opportnities.all(options.merge(customer_uuid: uuid))
     end
@@ -154,26 +172,49 @@ module ChartMogul
                                          tags: tags)[:tags]
     end
 
-    def add_custom_attributes!(*custom_attrs)
-      self.custom_attributes = custom_without_assign!(:post,
-                                                      "/v1/customers/#{uuid}/attributes/custom",
-                                                      custom: custom_attrs)[:custom]
-    end
-
-    def update_custom_attributes!(custom_attrs = {})
-      self.custom_attributes = custom_without_assign!(:put,
-                                                      "/v1/customers/#{uuid}/attributes/custom",
-                                                      custom: custom_attrs)[:custom]
-    end
-
-    def remove_custom_attributes!(*custom_attrs)
-      self.custom_attributes = custom_without_assign!(:delete,
-                                                      "/v1/customers/#{uuid}/attributes/custom",
-                                                      custom: custom_attrs)
-    end
-
-    def retrieve_attributes
-      custom_without_assign!(:get, "/v1/customers/#{uuid}/attributes")
+    # The custom attribute helpers (including .add_custom_attributes_by_email!)
+    # take override flags via the overrides: keyword, shaped
+    # { custom: { Name: true } } — unlike create!/update!, where the same flags
+    # nest under { attributes: { custom: { Name: true } } }. In
+    # update_custom_attributes!, an attribute literally named `overrides` must
+    # be passed in a braced hash, since the bare keyword is taken:
+    #   update_custom_attributes!({ overrides: 'value' })  updates the attribute
+    #   update_custom_attributes!(overrides: { ... })      sends override flags
+    def add_custom_attributes!(*custom_attrs, overrides: nil, **brace_less_attr)
+      custom_attrs << brace_less_attr unless brace_less_attr.empty?
+      body = { custom: custom_attrs }
+      body[:overrides] = overrides if overrides
+      response = custom_without_assign!(:post,
+                                        "/v1/customers/#{uuid}/attributes/custom",
+                                        body)
+      sync_custom_attribute_overrides(response)
+      self.custom_attributes = response[:custom]
+    end
+
+    def update_custom_attributes!(custom_attrs = {}, overrides: nil, **brace_less_attrs)
+      body = { custom: custom_attrs.merge(brace_less_attrs) }
+      body[:overrides] = overrides if overrides
+      response = custom_without_assign!(:put,
+                                        "/v1/customers/#{uuid}/attributes/custom",
+                                        body)
+      sync_custom_attribute_overrides(response)
+      self.custom_attributes = response[:custom]
+    end
+
+    def remove_custom_attributes!(*custom_attrs, overrides: nil, **brace_less_attr)
+      custom_attrs << brace_less_attr unless brace_less_attr.empty?
+      body = { custom: custom_attrs }
+      body[:overrides] = overrides if overrides
+      response = custom_without_assign!(:delete,
+                                        "/v1/customers/#{uuid}/attributes/custom",
+                                        body)
+      sync_custom_attribute_overrides(response)
+      self.custom_attributes = response[:custom]
+      response
+    end
+
+    def retrieve_attributes(options = {})
+      self.class.retrieve_attributes(uuid, options)
     end
 
     def merge_into!(other_customer)
@@ -194,8 +235,49 @@ module ChartMogul
       )
     end
 
+    # Responses echo the current override state, so only overrides assigned by
+    # the caller are serialized: replaying an echoed `true` flag on a later
+    # update! would re-protect stale in-memory values on the server. The echoed
+    # hash is deep-frozen and `dup` copies only the top level — request changes
+    # by assigning a freshly built hash, not by editing or duplicating the
+    # reader's result. Assigned intent is cleared by the response
+    # of the successful write (every write endpoint echoes `overrides`); an
+    # endpoint that stopped echoing would leave it set and resend it on the
+    # next update!.
+    def overrides=(value)
+      @overrides_requested = true
+      @overrides = value
+    end
+
+    def serialize_overrides
+      overrides if @overrides_requested
+    end
+
     private
 
+    def set_overrides(value)
+      @overrides_requested = false
+      @overrides = freeze_nested(value)
+    end
+
+    def freeze_nested(value)
+      value.each_value { |nested| freeze_nested(nested) } if value.is_a?(Hash)
+      value.freeze
+    end
+
+    # The custom attribute endpoints echo the customer's current custom
+    # attribute overrides, in the shape overrides[:attributes] uses. Synced
+    # through the read-only path so the flags are never marked for
+    # serialization; a pending explicitly assigned hash is not clobbered,
+    # keeping the serialize-exactly-once contract.
+    def sync_custom_attribute_overrides(response)
+      return if @overrides_requested || !response.key?(:overrides)
+
+      updated = (overrides || {}).reject { |key, _| key == :attributes }
+      updated[:attributes] = response[:overrides] unless response[:overrides].empty?
+      set_overrides(updated)
+    end
+
     def tags=(tags)
       @attributes[:tags] = tags
     end

data/lib/chartmogul/entity_note.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ChartMogul
+  class EntityNote < APIResource
+    set_resource_name 'EntityNote'
+    set_resource_path '/v1/notes'
+
+    readonly_attr :uuid
+    readonly_attr :associated_object
+    readonly_attr :associated_object_uuid
+    readonly_attr :author
+
+    writeable_attr :customer_uuid
+    writeable_attr :associated_object_identifier
+    writeable_attr :type
+    writeable_attr :text
+    writeable_attr :author_email
+    writeable_attr :call_duration
+    writeable_attr :created_at
+    writeable_attr :updated_at
+
+    include API::Actions::Create
+    include API::Actions::Destroy
+    include API::Actions::Retrieve
+    include API::Actions::Update
+
+    def self.all(options = {})
+      EntityNotes.all(options)
+    end
+  end
+
+  class EntityNotes < APIResource
+    set_resource_name 'EntityNotes'
+    set_resource_path '/v1/notes'
+
+    include Concerns::Entries
+    include Concerns::PageableWithCursor
+
+    set_entry_class EntityNote
+  end
+end

data/lib/chartmogul/note.rb

@@ -3,6 +3,7 @@
 require 'forwardable'
 
 module ChartMogul
+  # @deprecated Use {ChartMogul::EntityNote} instead. /v1/customer_notes is superseded by /v1/notes.
   class Note < APIResource
     set_resource_name 'CustomerNote'
     set_resource_path '/v1/customer_notes'
@@ -23,11 +24,55 @@ module ChartMogul
     include API::Actions::Retrieve
     include API::Actions::Update
 
+    # @deprecated Use {ChartMogul::EntityNote.all} instead.
     def self.all(options = {})
       Notes.all(options)
     end
+
+    # @deprecated Use {ChartMogul::EntityNote.create!} instead.
+    def self.create!(attributes = {})
+      warn 'DEPRECATION WARNING: the method ChartMogul::Note.create! is deprecated. Use ChartMogul::EntityNote.create! instead.'
+      super
+    end
+
+    # @deprecated Use {ChartMogul::EntityNote.retrieve} instead.
+    def self.retrieve(uuid, options = {})
+      warn 'DEPRECATION WARNING: the method ChartMogul::Note.retrieve is deprecated. Use ChartMogul::EntityNote.retrieve instead.'
+      super
+    end
+
+    # @deprecated Use {ChartMogul::EntityNote.update!} instead.
+    def self.update!(uuid, attributes = {})
+      warn 'DEPRECATION WARNING: the method ChartMogul::Note.update! is deprecated. Use ChartMogul::EntityNote.update! instead.'
+      super
+    end
+
+    # @deprecated Use {ChartMogul::EntityNote.destroy!} instead.
+    def self.destroy!(options = {})
+      warn 'DEPRECATION WARNING: the method ChartMogul::Note.destroy! is deprecated. Use ChartMogul::EntityNote.destroy! instead.'
+      super
+    end
+
+    # @deprecated Use {ChartMogul::EntityNote#create!} instead.
+    def create!
+      warn 'DEPRECATION WARNING: the method ChartMogul::Note#create! is deprecated. Use ChartMogul::EntityNote#create! instead.'
+      super
+    end
+
+    # @deprecated Use {ChartMogul::EntityNote#update!} instead.
+    def update!
+      warn 'DEPRECATION WARNING: the method ChartMogul::Note#update! is deprecated. Use ChartMogul::EntityNote#update! instead.'
+      super
+    end
+
+    # @deprecated Use {ChartMogul::EntityNote#destroy!} instead.
+    def destroy!
+      warn 'DEPRECATION WARNING: the method ChartMogul::Note#destroy! is deprecated. Use ChartMogul::EntityNote#destroy! instead.'
+      super
+    end
   end
 
+  # @deprecated Use {ChartMogul::EntityNotes} instead.
   class Notes < APIResource
     set_resource_name 'CustomerNotes'
     set_resource_path '/v1/customer_notes'
@@ -36,5 +81,11 @@ module ChartMogul
     include Concerns::PageableWithCursor
 
     set_entry_class Note
+
+    # @deprecated Use {ChartMogul::EntityNotes.all} instead.
+    def self.all(options = {})
+      warn 'DEPRECATION WARNING: the method ChartMogul::Notes.all is deprecated. Use ChartMogul::EntityNotes.all instead.'
+      super
+    end
   end
 end

data/lib/chartmogul/subscription.rb

@@ -42,6 +42,7 @@ module ChartMogul
     end
 
     def self.all(customer_uuid, options = {})
+      warn 'DEPRECATION WARNING: the method ChartMogul::Subscription.all is deprecated. Use ChartMogul::Metrics::Customers::Subscriptions.all instead.'
       Subscriptions.all(customer_uuid, options)
     end
 
@@ -71,6 +72,7 @@ module ChartMogul
     set_entry_class Subscription
 
     def self.all(customer_uuid, options = {})
+      warn 'DEPRECATION WARNING: the method ChartMogul::Subscriptions.all is deprecated. Use ChartMogul::Metrics::Customers::Subscriptions.all instead.'
       super(options.merge(customer_uuid: customer_uuid))
     end
 

data/lib/chartmogul/task.rb

@@ -8,10 +8,13 @@ module ChartMogul
     set_resource_path '/v1/tasks'
 
     readonly_attr :task_uuid
+    readonly_attr :associated_object
+    readonly_attr :associated_object_uuid
     readonly_attr :created_at
     readonly_attr :updated_at
 
     writeable_attr :customer_uuid
+    writeable_attr :associated_object_identifier
     writeable_attr :task_details
     writeable_attr :assignee
     writeable_attr :due_date

data/lib/chartmogul/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChartMogul
-  VERSION = '4.14.0'
+  VERSION = '4.15.0'
 end

data/lib/chartmogul.rb

@@ -60,6 +60,7 @@ require 'chartmogul/invoice'
 require 'chartmogul/customer_invoices'
 require 'chartmogul/customer'
 require 'chartmogul/note'
+require 'chartmogul/entity_note'
 require 'chartmogul/contact'
 require 'chartmogul/data_source'
 require 'chartmogul/data_source_settings/auto_churn_subscription_setting'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chartmogul-ruby
 version: !ruby/object:Gem::Version
-  version: 4.14.0
+  version: 4.15.0
 platform: ruby
 authors:
 - Petr Kopac
@@ -230,6 +230,7 @@ files:
 - lib/chartmogul/data_source_settings/auto_churn_subscription_setting.rb
 - lib/chartmogul/data_source_settings/processing_status.rb
 - lib/chartmogul/enrichment/customer.rb
+- lib/chartmogul/entity_note.rb
 - lib/chartmogul/errors/chartmogul_error.rb
 - lib/chartmogul/errors/configuration_error.rb
 - lib/chartmogul/errors/deprecated_parameter_error.rb