nzbn-ruby 0.1.0

data/lib/nzbn/models/base.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Base model class with common functionality
+    class Base
+      def initialize(attributes = {})
+        attributes.each do |key, value|
+          setter = "#{underscore(key.to_s)}="
+          send(setter, value) if respond_to?(setter)
+        end
+      end
+
+      def to_h
+        instance_variables.each_with_object({}) do |var, hash|
+          key = var.to_s.delete('@')
+          value = instance_variable_get(var)
+          hash[key] = serialize_value(value)
+        end
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      private
+
+      def underscore(str)
+        str.gsub(/::/, '/')
+           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .tr('-', '_')
+           .downcase
+      end
+
+      def camelize(str)
+        str.split('_').map.with_index { |word, i| i.zero? ? word : word.capitalize }.join
+      end
+
+      def serialize_value(value)
+        case value
+        when Base
+          value.to_h
+        when Array
+          value.map { |v| serialize_value(v) }
+        else
+          value
+        end
+      end
+
+      def build_model(klass, data)
+        return nil if data.nil?
+        return data.map { |item| build_model(klass, item) } if data.is_a?(Array)
+
+        klass.new(data)
+      end
+    end
+  end
+end

data/lib/nzbn/models/company.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Company details model
+    class Company < Base
+      attr_accessor :annual_return_filing_month, :financial_report_filing_month,
+                    :nzsx_code, :annual_return_last_filed, :has_constitution_filed,
+                    :country_of_origin, :overseas_company, :extensive_shareholding,
+                    :stock_exchange_listed, :shareholding, :ultimate_holding_company,
+                    :australian_company_number, :insolvencies, :removal_commenced
+    end
+
+    # Non-company entity details (limited partnerships, charities, etc.)
+    class NonCompany < Base
+      attr_accessor :annual_return_filing_month, :country_of_origin,
+                    :registered_union_status, :charities_number, :balance_date
+    end
+  end
+end

data/lib/nzbn/models/email_address.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Email address model
+    class EmailAddress < Base
+      attr_accessor :unique_identifier, :email_address, :email_purpose,
+                    :email_purpose_description, :start_date
+    end
+  end
+end

data/lib/nzbn/models/entity.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Entity model representing a basic NZBN entity
+    class Entity < Base
+      attr_accessor :entity_status_code, :entity_name, :nzbn, :entity_type_code,
+                    :entity_type_description, :entity_status_description,
+                    :registration_date, :source_register, :source_register_unique_identifier,
+                    :last_updated_date, :australian_business_number,
+                    :hibernation_status_code, :hibernation_status_description
+    end
+  end
+end

data/lib/nzbn/models/error_response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Error response from API
+    class ErrorResponse < Base
+      attr_accessor :status, :error_description, :error_code, :list
+
+      def errors
+        list || []
+      end
+    end
+
+    # Individual error field
+    class ErrorField < Base
+      attr_accessor :field, :message
+    end
+  end
+end

data/lib/nzbn/models/full_entity.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Full entity model with all details
+    class FullEntity < Base
+      attr_accessor :entity_status_code, :entity_name, :nzbn, :entity_type_code,
+                    :entity_type_description, :entity_status_description,
+                    :registration_date, :source_register, :source_register_unique_identifier,
+                    :last_updated_date, :australian_business_number,
+                    :hibernation_status_code, :hibernation_status_description,
+                    :email_addresses, :addresses, :industry_classifications,
+                    :phone_numbers, :websites, :trading_names, :privacy_settings,
+                    :company_details, :non_company_details, :roles,
+                    :trading_areas, :payment_bank_accounts, :gst_numbers,
+                    :supporting_information, :business_ethnicity_identifiers
+
+      def initialize(attributes = {})
+        super
+        parse_nested_objects(attributes)
+      end
+
+      private
+
+      def parse_nested_objects(attributes)
+        @addresses = build_addresses(attributes['addresses'])
+        @email_addresses = build_model_array(EmailAddress, attributes['emailAddresses'])
+        @phone_numbers = build_model_array(PhoneNumber, attributes['phoneNumbers'])
+        @websites = build_model_array(Website, attributes['websites'])
+        @trading_names = build_model_array(TradingName, attributes['tradingNames'])
+        @industry_classifications = build_model_array(IndustryClassification, attributes['industryClassifications'])
+        @roles = build_model_array(Role, attributes['roles'])
+        @privacy_settings = PrivacySettings.new(attributes['privacySettings']) if attributes['privacySettings']
+        @company_details = Company.new(attributes['company-details']) if attributes['company-details']
+      end
+
+      def build_addresses(data)
+        return [] unless data.is_a?(Hash) && data['addressList']
+
+        data['addressList'].map { |addr| Address.new(addr) }
+      end
+
+      def build_model_array(klass, data)
+        return [] unless data.is_a?(Array)
+
+        data.map { |item| klass.new(item) }
+      end
+    end
+  end
+end

data/lib/nzbn/models/industry_classification.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Industry classification (ANZSIC) model
+    class IndustryClassification < Base
+      attr_accessor :unique_identifier, :classification_code, :classification_description
+    end
+  end
+end

data/lib/nzbn/models/organisation_part.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Organisation part (OPN/GLN) model
+    class OrganisationPart < Base
+      attr_accessor :opn, :parent_nzbn, :parent_nzbn_name, :parent_gln, :name,
+                    :purposes, :function, :organisation_part_status,
+                    :addresses, :phone_numbers, :email_addresses,
+                    :gst_number, :payment_bank_account_number, :custom_data,
+                    :privacy, :nzbn_list, :start_date, :status_date
+    end
+  end
+end

data/lib/nzbn/models/phone_number.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Phone number model
+    class PhoneNumber < Base
+      attr_accessor :unique_identifier, :phone_purpose, :phone_purpose_description,
+                    :phone_country_code, :phone_area_code, :phone_number, :start_date
+
+      def formatted_number
+        parts = [phone_country_code, phone_area_code, phone_number].compact.reject(&:empty?)
+        parts.join(' ')
+      end
+    end
+  end
+end

data/lib/nzbn/models/privacy_settings.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Privacy settings model
+    class PrivacySettings < Base
+      attr_accessor :nzbn_private_information, :entity_type_private_information,
+                    :start_date_private_information, :status_private_information,
+                    :location_id_private_information, :name_private_information,
+                    :trading_name_private_information, :web_site_private_information,
+                    :business_classification_private_information, :gst_status_private_information,
+                    :phone_private_information, :email_private_information,
+                    :registered_address_private_information, :postal_address_private_information,
+                    :principal_address_private_information, :other_address_private_information,
+                    :partners_private_information, :trustees_private_information,
+                    :public_suggest_changes_yn, :gst_effective_date_private_information,
+                    :physical_address_private_information, :australian_business_number_private_information,
+                    :australian_company_number_private_information, :australian_service_address_private_information,
+                    :abn_private_information, :gst_number_private_information,
+                    :payment_bank_account_numbers_private_information,
+                    :service_address_private_information, :invoice_address_private_information,
+                    :delivery_address_private_information, :office_address_private_information,
+                    :business_ethnicity_private_information
+    end
+  end
+end

data/lib/nzbn/models/role.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Role model (director, partner, trustee, etc.)
+    class Role < Base
+      attr_accessor :unique_identifier, :role_type, :role_status,
+                    :start_date, :end_date, :asic_directorship_yn,
+                    :asic_name, :acn, :role_entity, :role_person,
+                    :role_address, :role_asic_address
+
+      def initialize(attributes = {})
+        super
+        @role_person = RolePerson.new(attributes['rolePerson']) if attributes['rolePerson']
+      end
+    end
+
+    # Person details within a role
+    class RolePerson < Base
+      attr_accessor :title, :first_name, :middle_names, :last_name
+
+      def full_name
+        [first_name, middle_names, last_name].compact.reject(&:empty?).join(' ')
+      end
+    end
+  end
+end

data/lib/nzbn/models/search_entity.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Search entity result from entity search
+    class SearchEntity < Base
+      attr_accessor :entity_status_code, :entity_name, :nzbn, :entity_type_code,
+                    :entity_type_description, :entity_status_description,
+                    :registration_date, :source_register_unique_id,
+                    :trading_names, :classifications, :previous_entity_names, :links
+
+      def initialize(attributes = {})
+        super
+        parse_nested_objects(attributes)
+      end
+
+      private
+
+      def parse_nested_objects(attributes)
+        @trading_names = build_model_array(TradingName, attributes['tradingNames'])
+        @classifications = build_model_array(IndustryClassification, attributes['classifications'])
+        @previous_entity_names = attributes['previousEntityNames'] || []
+      end
+
+      def build_model_array(klass, data)
+        return [] unless data.is_a?(Array)
+
+        data.map { |item| klass.new(item) }
+      end
+    end
+  end
+end

data/lib/nzbn/models/search_response.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Paginated search response
+    class SearchResponse < Base
+      attr_accessor :page_size, :page, :total_items, :sort_by, :sort_order, :items, :links
+
+      def initialize(attributes = {}, item_class: nil)
+        super(attributes)
+        @items = parse_items(attributes['items'], item_class) if item_class
+      end
+
+      def each(&block)
+        items.each(&block)
+      end
+
+      def map(&block)
+        items.map(&block)
+      end
+
+      def first
+        items.first
+      end
+
+      def last
+        items.last
+      end
+
+      def empty?
+        items.nil? || items.empty?
+      end
+
+      def count
+        items&.length || 0
+      end
+
+      alias size count
+      alias length count
+
+      private
+
+      def parse_items(data, klass)
+        return [] unless data.is_a?(Array)
+
+        data.map { |item| klass.new(item) }
+      end
+    end
+  end
+end

data/lib/nzbn/models/trading_name.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Trading name model
+    class TradingName < Base
+      attr_accessor :unique_identifier, :name, :start_date, :end_date
+    end
+  end
+end

data/lib/nzbn/models/watchlist.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Watchlist model
+    class Watchlist < Base
+      attr_accessor :watchlist_id, :name, :user_id, :from_date, :to_date,
+                    :organisation_id, :channel, :frequency, :wildcard,
+                    :change_event_types, :push_endpoint, :authorization_token,
+                    :admin_email_address, :watchlist_email_addresses,
+                    :last_successful_change_notice_id, :suspended, :links, :nzbns
+    end
+  end
+end

data/lib/nzbn/models/website.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Website model
+    class Website < Base
+      attr_accessor :unique_identifier, :url, :website_purpose, :start_date
+    end
+  end
+end

data/lib/nzbn/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Nzbn
+  VERSION = '0.1.0'
+end

data/lib/nzbn.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'nzbn/version'
+require_relative 'nzbn/configuration'
+require_relative 'nzbn/error'
+require_relative 'nzbn/client'
+
+# Models
+require_relative 'nzbn/models/base'
+require_relative 'nzbn/models/entity'
+require_relative 'nzbn/models/full_entity'
+require_relative 'nzbn/models/search_entity'
+require_relative 'nzbn/models/address'
+require_relative 'nzbn/models/role'
+require_relative 'nzbn/models/trading_name'
+require_relative 'nzbn/models/phone_number'
+require_relative 'nzbn/models/email_address'
+require_relative 'nzbn/models/website'
+require_relative 'nzbn/models/industry_classification'
+require_relative 'nzbn/models/privacy_settings'
+require_relative 'nzbn/models/company'
+require_relative 'nzbn/models/watchlist'
+require_relative 'nzbn/models/organisation_part'
+require_relative 'nzbn/models/search_response'
+require_relative 'nzbn/models/error_response'
+
+# API Resources
+require_relative 'nzbn/api/entities'
+require_relative 'nzbn/api/addresses'
+require_relative 'nzbn/api/roles'
+require_relative 'nzbn/api/trading_names'
+require_relative 'nzbn/api/phone_numbers'
+require_relative 'nzbn/api/email_addresses'
+require_relative 'nzbn/api/websites'
+require_relative 'nzbn/api/industry_classifications'
+require_relative 'nzbn/api/privacy_settings'
+require_relative 'nzbn/api/company_details'
+require_relative 'nzbn/api/watchlists'
+require_relative 'nzbn/api/organisation_parts'
+require_relative 'nzbn/api/history'
+
+# NZBN Ruby Client - New Zealand Business Number API
+#
+# @example Basic usage
+#   Nzbn.configure do |config|
+#     config.api_key = 'your-api-key'
+#   end
+#
+#   client = Nzbn::Client.new
+#   entities = client.entities.search(search_term: 'Company Name')
+#
+module Nzbn
+  DEFAULT_BASE_URL = 'https://api.business.govt.nz/gateway/nzbn/v5'
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      self.configuration = Configuration.new
+    end
+  end
+end

data/nzbn-ruby.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'lib/nzbn/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'nzbn-ruby'
+  spec.version       = Nzbn::VERSION
+  spec.authors       = ['Nhan Nguyen']
+  spec.email         = ['nnhansg@gmail.com']
+
+  spec.summary       = 'Ruby client for the New Zealand Business Number (NZBN) API'
+  spec.description   = 'A Ruby gem for interacting with the NZBN API v5. Search entities, manage watchlists, and access NZ business data.'
+  spec.homepage      = 'https://github.com/nnhansg/nzbn-ruby'
+  spec.license       = 'MIT'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.files += Dir['lib/**/*.rb']
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'faraday', '>= 1.0', '< 3.0'
+  spec.add_dependency 'faraday-multipart', '~> 1.0'
+
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'webmock', '~> 3.0'
+end