vantaca 0.3.0

data/lib/vantaca/ledger.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  # Methods which allow posting and deletion of ledger entries.
+  module Ledger
+    # Create a ledger entry for a specific homeowner.
+    #
+    # @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 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.
+    def create_ledger_entry(account, type:, charge_id:, date:, amount:, description:) # rubocop:disable Metrics/ParameterLists
+      get(
+        '/write/createLedger',
+        account:, type:, assocChgID: charge_id, ledgerDate: date, amount:, Descr: description
+      )
+    end
+
+    def delete_ledger_entry(ledger_id)
+      get('/write/ledgerDelete', ownerLedgerID: ledger_id)
+    end
+  end
+end

data/lib/vantaca/models/action_category.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # Information about an action category
+    class ActionCategory < Base
+      # @return [Integer] unique identifier for action category
+      def id = data['ActionCategoryID']
+
+      # @return [String] action category description
+      def description = data['Descr']
+    end
+  end
+end

data/lib/vantaca/models/action_type.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # Information about an action type
+    class ActionType < Base
+      # @return [Integer] unique identifier for action type
+      def id = data['ActionTypeID']
+
+      # @return [Integer] unique identifier for action category
+      def category_id = data['ActionCategoryID']
+
+      # @return [String] action type description
+      def description = data['Descr']
+
+      def created = Time.parse(data['CreatedDate'])
+
+      def updated = Time.parse(data['LastUpdatedDate'])
+    end
+  end
+end

data/lib/vantaca/models/address.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # Information about an address, received from the Vantaca API
+    class Address < Base
+      attr_reader :owner
+
+      def initialize(data, owner:)
+        super(data)
+
+        @owner = owner
+      end
+
+      def id = data['addrID']
+
+      def label = data['label']
+
+      def mailing? = data['isMailing']
+
+      def international? = data['isInternational']
+
+      def address1 = data['address1']
+
+      def address2 = data['address2']
+
+      def city = data['city']
+
+      def state = data['state']
+
+      def zip = data['zip']
+
+      def to_s
+        [
+          (data['address1'] if data['address1'].match?(/[[:graph:]]/)),
+          (data['address2'] if data['address2'].match?(/[[:graph:]]/)),
+          city_state_zip
+        ].compact.map(&:strip).join("\n")
+      end
+      alias formatted to_s
+
+      protected
+
+      def city_state_zip
+        # Foreign addresses do not have City/State/Zip
+        return unless data['city'] && data['state'] && data['zip']
+
+        "#{data['city']}, #{data['state']} #{data['zip']}"
+      end
+    end
+  end
+end

data/lib/vantaca/models/base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # A basic class which all model classes inherit from, allowing easy access to the raw data.
+    class Base
+      attr_reader :data
+
+      def initialize(data)
+        @data = data
+      end
+
+      def dig(...) = @data.dig(...)
+
+      def [](key) = @data[key]
+    end
+  end
+end

data/lib/vantaca/models/community.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # Information about a community, received from the Vantaca API
+    class Community < Base
+      def id = data['assocCode']
+
+      def name = data['assocName']
+
+      def tax_id = data['taxID']
+
+      def charges = data['charges'] || []
+
+      def late_fees = data['lateFees'] || []
+    end
+  end
+end

data/lib/vantaca/models/document.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # Information about a document, received from the Vantaca API
+    class Document < Base
+      SECURITY_LEVELS = %w[Public Homeowners Board Staff].freeze
+
+      def id = data['imgID']
+
+      def name = data['docName']
+
+      def folder_path = data['folderPath']
+
+      def security_id = data['securityID']
+    end
+  end
+end

data/lib/vantaca/models/email.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # Information about an email address, received from the Vantaca API
+    class Email < Base
+      attr_reader :owner
+
+      def initialize(data, owner:)
+        super(data)
+
+        @owner = owner
+      end
+
+      def id = data['emailID']
+
+      def label = data['label']
+
+      def email = data['email']
+
+      def primary? = data['isPrimary']
+    end
+  end
+end

data/lib/vantaca/models/owner.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # Information about an owner, received from the Vantaca API
+    class Owner < Base
+      def id = data['hoid']
+
+      def account = data['accountNo']
+
+      def property_id = data['propertyID']
+
+      def in_collections? = data['collectionStatus'] != ''
+
+      def addresses
+        @addresses ||= data['addresses'].map { Vantaca::Models::Address.new(it, owner: self) }
+      end
+
+      def emails
+        @emails ||= data['emails'].map { Vantaca::Models::Email.new(it, owner: self) }
+      end
+
+      def phones
+        @phones ||= data['phones'].map { Vantaca::Models::Phone.new(it, owner: self) }
+      end
+
+      def offsite? = data['mailingAddressType'] == 'OffSiteMailingAddress'
+
+      # This is the *primary* mailing address, if different from the property address
+      def offsite_mailing_address = (addresses.find { it.id == data['mailingAddressID'] } if offsite?)
+
+      def alternate_mailing_addresses
+        primary_offsite_address_id = offsite? ? data['mailingAddressID'] : nil
+
+        addresses.select { it.mailing? && it.id != primary_offsite_address_id }
+      end
+
+      def move_in_date = (Time.parse data['settleDate'] if data['settleDate'])
+
+      def move_out_date = (Time.parse data['previousOwner'] if data['previousOwner'])
+
+      def payment_plan? = data['hasPaymentPlan']
+
+      def balance = data['balance']
+
+      def overall_balance = data['overallBalance']
+
+      def current_owner? = data['previousOwner'].nil?
+
+      def communication_preferences
+        {
+          communication: data['CommPref'],
+          billing: data['BillingPref']
+        }
+      end
+    end
+  end
+end

data/lib/vantaca/models/phone.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # Information about a phone number, received from the Vantaca API
+    class Phone < Base
+      attr_reader :owner
+
+      def initialize(data, owner:)
+        super(data)
+
+        @owner = owner
+      end
+
+      def id = data['phoneID']
+
+      def label = data['label']
+
+      def phone = data['phone']
+
+      def primary? = data['isPrimary']
+    end
+  end
+end

data/lib/vantaca/models/provider.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # Information about a provider (vendor)
+    class Provider < Base
+      # @return [Integer] unique identifier for service provider
+      def id = @data['providerID']
+
+      # @return [String] service provider name
+      def name = @data['name']
+
+      # @return [Integer] service provider federal tax identification number
+      def tax_id = @data['taxID']
+
+      # @return [Boolean] if **true**, provider is compliant, else, **false**
+      def compliant? = @data['compliant']
+
+      # @return [Boolean]
+      def on_hold? = @data['onHold']
+
+      # @return [String] reason service provider is on hold
+      def hold_reason = @data['onHoldReason']
+
+      # @return [String] the grouping of the provider's compliance (this is an open-ended text field)
+      def compliance_group = @data['complianceGroup']
+
+      # @return [String] the status of the provider's compliance (open-ended text field)
+      def compliance_status = @data['complianceStatus']
+
+      # @return [Boolean]
+      def compliance_exempt? = @data['complianceExempt']
+
+      # @return [String] primary email
+      def email = @data['email']
+
+      # @return [String] primary phone
+      def phone = @data['phone']
+
+      # @return [String] primary fax
+      def fax = @data['fax']
+
+      # @return [Boolean]
+      def preferred? = @data['preferred']
+
+      # @return [Vantaca::Models::ProviderInsurance, nil] list of insurance policies for provider, or nil if not
+      #   requested
+      def insurance
+        return unless @data['providerInsurance']
+
+        @insurance ||= @data['providerInsurance'].map { Vantaca::Models::ProviderInsurance.new(it, provider: self) }
+      end
+    end
+  end
+end

data/lib/vantaca/models/provider_insurance.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  module Models
+    # A single insurance record - in our case, populated by Vive.
+    class ProviderInsurance < Base
+      # !@attribute [r] provider
+      #   @return [Vantaca::Models::Provider]
+      attr_reader :provider
+
+      def initialize(data, provider:)
+        super(data)
+
+        @provider = provider
+      end
+
+      # @return [Integer]
+      def id = data['providerInsuranceID']
+
+      # @return [String]
+      def type = data['insuranceType']
+
+      # @return [String]
+      def account = data['accountNo']
+
+      # For now, I'm going to assume that all insurance records include an expiration date.
+      # @return [Time]
+      def expiration_date = Time.parse(data['expirationDate'])
+
+      # @return [Boolean]
+      def expired? = expiration_date < Time.now
+
+      # @return [Boolean]
+      def required? = @data['isRequired']
+    end
+  end
+end

data/lib/vantaca/owners.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  # Methods which load or modify one or more owners.
+  module Owners
+    OWNER_PARAMETERS = {
+      bk_list: :includeOwnerBKList,
+      charges: :includeOwnerChargeTransactions,
+      next_assessment: :includeNextAssessment,
+      transactions: :includeOwnerTransactions,
+      breakdown: :includebalanceByChargeType
+    }.freeze
+
+    # Load a list of all owners in a specific community
+    #
+    # @param assoc_code [String] the 3-4 character association code for a community
+    # @option opts [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 in this community.
+    def community_owners(assoc_code, **options)
+      params = owner_parameters(assoc_code, options)
+
+      response = get('/read/Association', **params)
+
+      raise Vantaca::Errors::NotFoundError unless response
+
+      response.dig(0, 'owners').map { Vantaca::Models::Owner.new(it) }
+    end
+
+    # 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
+    # @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:)
+
+      response = get('/read/Association', **params)
+
+      raise Vantaca::Errors::NotFoundError unless response
+
+      Vantaca::Models::Owner.new response.dig(0, 'owners', 0)
+    end
+
+    # 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
+    # @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)
+
+      response = get('/read/Association', **params)
+
+      raise Vantaca::Errors::NotFoundError unless response
+
+      response.dig(0, 'owners').map { Vantaca::Models::Owner.new(it) }
+    end
+
+    # Load a specific homeowner - this currently loads only the first owner record, even if the owner has multiple
+    # 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
+    # @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)
+
+      response = get('/read/Association', **params)
+
+      raise Vantaca::Errors::NotFoundError unless response
+
+      Vantaca::Models::Owner.new response.dig(0, 'owners', 0)
+    end
+
+    # This data is already included in the basic owner data - this endpoint isn't very useful.
+    def communication_preferences(owner_id)
+      response = get('/read/getCommPreference', hoID: owner_id)
+
+      raise Vantaca::Errors::NotFoundError unless response
+
+      {
+        communication: response['commpref'],
+        billing: response['billingpref']
+      }
+    end
+
+    # Update the communication preferences for a homeowner.
+    #
+    # @param owner_id [Fixnum] 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]
+    def update_communication_preferences(owner_id, communication: nil, billing: nil)
+      raise ArgumentError, 'At least communication or billing must be passed.' unless communication || billing
+
+      params = { hoid: owner_id, commpref: communication, billingpref: billing }
+
+      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)
+      params = {
+        hoID: owner_id,
+        firstName: first_name,
+        lastName: last_name,
+        spouseFirstName: spouse_first_name,
+        spouseLastName: spouse_last_name,
+        businessName: business_name
+      }
+
+      post('/write/nameUpdate', params.compact)
+    end
+
+    protected
+
+    def owner_parameters(community, options)
+      params = { includeOwners: true, assocCode: community }
+
+      OWNER_PARAMETERS.values_at(*Array(options[:include])).compact.each do |vantaca_parameter|
+        params[vantaca_parameter] = true
+      end
+
+      params.compact
+    end
+  end
+end

data/lib/vantaca/phones.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  # Methods which allow creation, modification, and deletion of homeowner phone numbers.
+  module Phones
+    # @param homeowner_id [Integer] The ID of the homeowner
+    # @param phone_attrs [Hash] The phone number details
+    # @option phone_attrs [String] :phone (required) The ten-digit numeric phone number
+    # @option phone_attrs [Boolean] :isPrimary Whether this is the primary phone number
+    # @option phone_attrs [String] :label Optional label for the phone number (e.g., 'Mobile', 'Home')
+    # @return [Response] The API response from the phone creation endpoint
+    def create_phone_number(homeowner_id, phone_attrs)
+      post('/write/phoneCreate', phone_attrs.merge(hoid: homeowner_id))
+    end
+
+    # @param phone_number_id [Integer] The ID of the phone number to update
+    # @param phone_attrs [Hash] The updated phone number details
+    # @option phone_attrs [String] :phone (required) The ten-digit numeric phone number
+    # @option phone_attrs [Boolean] :isPrimary Whether this is the primary phone number
+    # @option phone_attrs [String] :label Optional label for the phone number (e.g., 'Mobile', 'Home')
+    # @return [Response] The API response from the phone update endpoint
+    def update_phone_number(phone_number_id, phone_attrs)
+      post('/write/phoneUpdate', phone_attrs.merge(phoneID: phone_number_id))
+    end
+
+    # @param phone_number_id [Integer] The ID of the phone number to delete
+    # @return [Response] The API response from the phone deletion endpoint
+    def delete_phone_number(phone_number_id)
+      post('/write/phoneDestroy', { phoneID: phone_number_id })
+    end
+  end
+end

data/lib/vantaca/providers.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  # Methods which load or modify one or more providers.
+  module Providers
+    PROVIDER_PARAMETERS = { insurance: :includeInsurance }.freeze
+
+    # Load a list of all providers.
+    #
+    # @option opts [Symbol, Array<Symbol>] :include Include additional information, using keys from PROVIDER_PARAMETERS
+    # @return [Array<Vantaca::Models::Provider>] a list of all providers.
+    def providers(**options)
+      response = get('/read/provider', **provider_parameters(options))
+
+      raise Vantaca::Errors::NotFoundError unless response
+
+      response.map { Vantaca::Models::Provider.new(it) }
+    end
+
+    # Load a single provider by their internal Vantaca ID.
+    #
+    # @param id [String] the internal Vantaca ID of a provider
+    # @option opts [Symbol, Array<Symbol>] :include Include additional information, using keys from PROVIDER_PARAMETERS
+    # @return [Vantaca::Models::Provider] a single provider record
+    # @raise [Vantaca::Errors::NotFoundError] if the provider does not exist
+    def provider(id, **options)
+      response = get('/read/providerSingle', **provider_parameters(options), providerID: id)
+
+      Vantaca::Models::Provider.new response
+    rescue Vantaca::Errors::ApiError
+      raise Vantaca::Errors::NotFoundError
+    end
+
+    # Update a provider by their internal Vantaca ID.
+    #
+    # @param id [String] the internal Vantaca ID of a provider
+    # @param attributes [Hash] a hash of attributes to update
+    # @return [nil] returns nil if the update was successful
+    # @raise [Vantaca::Errors::NotFoundError] if the provider does not exist
+    def update_provider(id, **provider_attributes)
+      post('/write/providerUpdate', provider_attributes.merge(providerID: id))
+    rescue Vantaca::Errors::ApiError
+      raise Vantaca::Errors::NotFoundError
+    end
+
+    protected
+
+    def provider_parameters(options)
+      params = {}
+
+      PROVIDER_PARAMETERS.values_at(*Array(options[:include])).compact.each do |vantaca_parameter|
+        params[vantaca_parameter] = true
+      end
+
+      params
+    end
+  end
+end

data/lib/vantaca/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+module Vantaca
+  VERSION = '0.3.0'
+end

data/lib/vantaca.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Copyright (c) Valencia Management Group
+# All rights reserved.
+
+require 'httparty'
+require 'json'
+require 'tempfile'
+require 'time'
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+# The module we're all here for.
+module Vantaca
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+
+    yield(configuration) if block_given?
+
+    configuration
+  end
+end