vantaca 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17d644bafa17b33e40ce3695a575773dc6a4c32500b20463e5a85849d9e7f7ce
-  data.tar.gz: 1d1644fde830360cec3b38860f124528a32411613b5d0d4693866f01f2984bcf
+  metadata.gz: c20dee21412de48a8af0be81b7644a2eb0ea379e953776e321aae3d6b148256c
+  data.tar.gz: 4d9fb4973d18f7a73caa2afc9a396ccef65f3988df1e7cb9613ee627f53838ab
 SHA512:
-  metadata.gz: 69c22312ab4573a406982fed1c14ada85cc2bbeed1b4dbc197266ffda5e6b07d924588575739feeb6b1887a7c04b916b53d7017dde71cfce1712cd6b3959c9fe
-  data.tar.gz: 205fef825382c52847c32aa83d8ae304cd7bd74372e40602e22aa97fbcb3af181ae1a3eb7c5169d077bdc350d42ac9c0bdf173bd2ab428a3b322a6a474e92093
+  metadata.gz: c9a0d82584f6f99953ee7046b7fd2da5baf3e2203937eac1acb0cb127e26cc55c62e9c0c8ca80d1fe3e9b41fe87c7aaf701f6c361b93823771941286de204cf0
+  data.tar.gz: 06aa883955d84f50231bd71a28e79b53648cf7918c6220b7ec269bfe3ff5c6cd68d14bff64844fb6b7c589eaa4e852f54b8d939c283a49142218706fb09a3baa

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    vantaca (0.3.0)
+    vantaca (0.3.1)
       httparty (~> 0.24)
       zeitwerk (~> 2.7)
 
@@ -144,7 +144,7 @@ CHECKSUMS
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
   unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
-  vantaca (0.3.0)
+  vantaca (0.3.1)
   vcr (6.4.0) sha256=077ac92cc16efc5904eb90492a18153b5e6ca5398046d8a249a7c96a9ea24ae6
   webmock (3.26.1) sha256=4f696fb57c90a827c20aadb2d4f9058bbff10f7f043bd0d4c3f58791143b1cd7
   zeitwerk (2.7.5) sha256=d8da92128c09ea6ec62c949011b00ed4a20242b255293dd66bf41545398f73dd

data/README.md

@@ -1,3 +1,3 @@
 # Vantaca API Gem
 
-[![Build Status](https://github.com/ValenciaMgmt/Vantaca/workflows/RSpec/badge.svg?branch=master)](https://github.com/ValenciaMgmt/Vantaca/actions?query=workflow%3A%22RSpec%22)
+[![Build Status](https://github.com/Valencia-Management-Group/Vantaca/actions/workflows/ruby.yml/badge.svg)](https://github.com/Valencia-Management-Group/Vantaca/actions/workflows/ruby.yml)

data/lib/vantaca/action_items.rb

@@ -17,6 +17,9 @@ module Vantaca
       Array(response).map { Vantaca::Models::ActionCategory.new(it) }
     end
 
+    # Load all active action types and their steps.
+    #
+    # @return [Array<Vantaca::Models::ActionType>] active action types
     def action_types
       response = get('/read/actionTypeList')
 
@@ -24,5 +27,93 @@ module Vantaca
 
       Array(response).map { Vantaca::Models::ActionType.new(it) }
     end
+
+    # Retrieve details about an action item.
+    #
+    # @param action_item_id [Integer] the internal Vantaca ID of an action item
+    # @return [Vantaca::Models::ActionItem] the action item with the specified ID
+    # @raise [Vantaca::Errors::NotFoundError] if the action item does not exist
+    def action_item(action_item_id)
+      response = get('/read/getActionItem', actionItemID: action_item_id)
+
+      raise Vantaca::Errors::NotFoundError unless response
+
+      Vantaca::Models::ActionItem.new response
+    end
+
+    # Create a new action item for a specific association. Only action items in the Standard category can be created
+    # through the API.
+    #
+    # @param assoc_code [String] the 3-4 character association code for a community
+    # @param action_type_id [Integer] the internal Vantaca action type ID
+    # @param options [Hash] Additional options for the action item
+    # @option options [Integer, nil] :step_id Unique identifier for an action item step.
+    # @option options [Integer, nil] :property_id Unique identifier for a property related to this action item.
+    # @option options [String, nil] :description A description of the action item.
+    # @option options [String, nil] :subject A short subject line for the action item.
+    # @option options [Date, nil] :followup_date The follow-up date for this action item.
+    # @option options [Date, nil] :due_date The due date for this action item.
+    # @option options [Hash] :file An optional file attachment for this action item, with keys :path (the local file
+    #   path) and :is_primary (a boolean indicating whether this is the primary attachment for the action item).
+    #
+    # @return [Hash] the API response for the created action item
+    def create_association_action_item(assoc_code, action_type_id:, **options)
+      post(
+        '/write/createStandardActionItem',
+        action_item_body(options[:file]),
+        assocCode: assoc_code,
+        actionTypeID: action_type_id,
+        **action_item_parameters(options)
+      )
+    end
+
+    # Create a new action item for a specific account. Only action items in the Standard category can be created
+    # through the API.
+    #
+    # @param account_no [String] the 7-9 character account number for a property's homeowner
+    # @param action_type_id [Integer] the internal Vantaca action type ID
+    # @param options [Hash] Additional options for the action item
+    # @option options [Integer, nil] :step_id Unique identifier for an action item step.
+    # @option options [Integer, nil] :property_id Unique identifier for a property related to this action item.
+    # @option options [String, nil] :description A description of the action item.
+    # @option options [String, nil] :subject A short subject line for the action item.
+    # @option options [Date, nil] :followup_date The follow-up date for this action item.
+    # @option options [Date, nil] :due_date The due date for this action item.
+    # @option options [Hash] :file An optional file attachment for this action item, with keys :path (the local file
+    #   path) and :is_primary (a boolean indicating whether this is the primary attachment for the action item).
+    #
+    # @return [Hash] the API response for the created action item
+    def create_account_action_item(account_no, action_type_id:, **options)
+      post(
+        '/write/createStandardActionItem',
+        action_item_body(options[:file]),
+        accountNo: account_no,
+        actionTypeID: action_type_id,
+        **action_item_parameters(options)
+      )
+    end
+
+    protected
+
+    def action_item_parameters(options)
+      {
+        stepID: options[:step_id],
+        propertyID: options[:property_id],
+        description: options[:description],
+        subject: options[:subject],
+        dueDate: options[:due_date]&.iso8601,
+        followupDate: options[:followup_date]&.iso8601
+      }
+    end
+
+    def action_item_body(file)
+      return unless file
+
+      {
+        file: Base64.strict_encode64(File.read(file[:path])),
+        fileName: File.basename(file[:path]),
+        isPrimary: file[:is_primary] || false
+      }
+    end
   end
 end

data/lib/vantaca/ledger.rb

@@ -10,7 +10,7 @@ module Vantaca
     #
     # @param account [String] The 7-9 character account number for the homeowner, e.g. 'ABC12345'
     # @param type [String] Type of transaction. Possible values: Charge, Adjustment, Writeoff.
-    # @param charge_id [Fixnum] The association Charge ID associated with this owners account.
+    # @param charge_id [Integer] The association Charge ID associated with this owners account.
     # @param date [String] The ledger date for this transaction, e.g. '2020-12-25'
     # @param amount [Float] Transaction amount. Must be greater than 0.
     # @param description [String] Description of the transaction.

data/lib/vantaca/models/action_item.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # Information about an action category
+    class ActionItem < Base
+      # @return [Integer] unique identifier for action category
+      def type_id = data['actionTypeID']
+
+      # @return [Integer] unique identifier for action step
+      def step_id = data['actionStepID']
+
+      # @return [Integer] unique identifier for action category
+      def category_id = data['actionCategoryID']
+
+      # @return [String] action category description
+      def description = data['descr']
+
+      # @return [Time] date and time when this action item was created
+      def created_at = Time.parse(data['created'])
+
+      # @return [Time] date and time when this action item was last modified
+      def updated_at = Time.parse(data['lastModified'])
+
+      # @return [String] the 3-4 character association code for the community
+      def assoc_code = data['assocCode']
+
+      # @return [Array<Vantaca::Models::ActionItemNote>] notes associated with this action item
+      def notes = data['actionItemNotes'].map { Vantaca::Models::ActionItemNote.new(it) }
+    end
+  end
+end

data/lib/vantaca/models/action_item_note.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # Information about an action item note
+    class ActionItemNote < Base
+      # @return [Integer] unique identifier for action step
+      def step_id = data['actionStepID']
+
+      # @return [String] action item note
+      def note = data['note']
+
+      # @return [Time] date and time when this action item was created
+      def created_at = Time.parse(data['created'])
+    end
+  end
+end

data/lib/vantaca/owners.rb

@@ -32,7 +32,8 @@ module Vantaca
     # Loading an owner by their account number doesn't need a community code, since the account numbers are unique.
     #
     # @param account [String] the 7-9 character account number for a property's homeowner
-    # @option opts [Symbol, Array<Symbol>] :include Include additional information, using keys from OWNER_PARAMETERS
+    # @param options [Hash] Additional options for loading information
+    # @option options [Symbol, Array<Symbol>] :include Include additional information, using keys from OWNER_PARAMETERS
     # @return [Vantaca::Models::Owner] a list of all current and former owners in this community.
     def account_owner(account, **options)
       params = owner_parameters(nil, options).merge(account:)
@@ -47,8 +48,9 @@ module Vantaca
     # Load a list of all owners for a specific property
     #
     # @param assoc_code [String] the 3-4 character association code for a community
-    # @param property_id [Fixnum] the internal Vantaca property ID
-    # @option opts [Symbol, Array<Symbol>] :include Include additional information, using keys from OWNER_PARAMETERS
+    # @param property_id [Integer] the internal Vantaca property ID
+    # @param options [Hash] Additional options for loading information
+    # @option options [Symbol, Array<Symbol>] :include Include additional information, using keys from OWNER_PARAMETERS
     # @return [Array<Vantaca::Models::Owner>] a list of all current and former owners for this property.
     def property_owners(assoc_code, property_id, **options)
       params = owner_parameters(assoc_code, options).merge(propertyID: property_id)
@@ -64,8 +66,9 @@ module Vantaca
     # properties in this community.
     #
     # @param assoc_code [String] the 3-4 character association code for a community
-    # @param owner_id [Fixnum] the internal Vantaca homeowner ID
-    # @option opts [Symbol, Array<Symbol>] :include Include additional information, using keys from OWNER_PARAMETERS
+    # @param owner_id [Integer] the internal Vantaca homeowner ID
+    # @param options [Hash] Additional options for loading information
+    # @option options [Symbol, Array<Symbol>] :include Include additional information, using keys from OWNER_PARAMETERS
     # @return [Vantaca::Models::Owner] the owner record for this homeowner
     def owner(assoc_code, owner_id, **options)
       params = owner_parameters(assoc_code, options).merge(Hoid: owner_id)
@@ -91,7 +94,7 @@ module Vantaca
 
     # Update the communication preferences for a homeowner.
     #
-    # @param owner_id [Fixnum] the internal Vantaca homeowner ID
+    # @param owner_id [Integer] the internal Vantaca homeowner ID
     # @param communication [String] the new general communication preference, accepted values: Paper, Email, App, Text
     # @param billing [String] the internal the new billing communication preference, accepted values: Paper, Text, Email
     # @return [true]
@@ -103,14 +106,23 @@ module Vantaca
       post('/write/commPrefUpdate', params.compact)
     end
 
-    def update_name(owner_id, first_name:, last_name:, spouse_first_name: nil, spouse_last_name: nil, business_name: nil)
+    # Update name fields for a homeowner. Use empty strings to clear existing values, or nil to leave them unchanged.
+    #
+    # @param owner_id [Integer] the internal Vantaca homeowner ID
+    # @param options [Hash] the name fields to update
+    # @option options [String, nil] :first_name The homeowner's first name
+    # @option options [String, nil] :last_name The homeowner's last name
+    # @option options [String, nil] :spouse_first_name The homeowner's spouse's first name
+    # @option options [String, nil] :spouse_last_name The homeowner's spouse's last name
+    # @option options [String, nil] :business_name The homeowner's business name
+    def update_name(owner_id, **options)
       params = {
         hoID: owner_id,
-        firstName: first_name,
-        lastName: last_name,
-        spouseFirstName: spouse_first_name,
-        spouseLastName: spouse_last_name,
-        businessName: business_name
+        firstName: options[:first_name],
+        lastName: options[:last_name],
+        spouseFirstName: options[:spouse_first_name],
+        spouseLastName: options[:spouse_last_name],
+        businessName: options[:business_name]
       }
 
       post('/write/nameUpdate', params.compact)

data/lib/vantaca/version.rb

@@ -4,5 +4,5 @@
 # All rights reserved.
 
 module Vantaca
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vantaca
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Steven Hoffman
@@ -61,6 +61,8 @@ files:
 - lib/vantaca/errors.rb
 - lib/vantaca/ledger.rb
 - lib/vantaca/models/action_category.rb
+- lib/vantaca/models/action_item.rb
+- lib/vantaca/models/action_item_note.rb
 - lib/vantaca/models/action_type.rb
 - lib/vantaca/models/address.rb
 - lib/vantaca/models/base.rb