nzbn-ruby 0.1.0

data/lib/nzbn/api/organisation_parts.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Api
+    # Organisation Parts API (OPN/GLN management)
+    class OrganisationParts
+      def initialize(client)
+        @client = client
+      end
+
+      # Search organisation parts
+      #
+      # @param nzbn [String] Parent NZBN to search within
+      # @param opn [String] OPN to search for
+      # @param name [String] Name filter
+      # @param function [String] Function filter (FUNCTION, PHYSICAL_LOCATION, DIGITAL_LOCATION)
+      # @param status [String] Status filter (ACTIVE, INACTIVE)
+      # @param page [Integer] Page number
+      # @param page_size [Integer] Results per page
+      # @return [Models::SearchResponse] Paginated results
+      #
+      def search(nzbn: nil, opn: nil, name: nil, function: nil, status: nil, page: nil, page_size: nil)
+        params = {}
+        params['nzbn'] = nzbn if nzbn
+        params['opn'] = opn if opn
+        params['name'] = name if name
+        params['function'] = function if function
+        params['status'] = status if status
+        params['page'] = page if page
+        params['page-size'] = page_size if page_size
+
+        response = @client.get('/entities/organisation-parts', params)
+        Models::SearchResponse.new(response, item_class: Models::OrganisationPart)
+      end
+
+      # List organisation parts for an entity
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Models::OrganisationPart>] List of organisation parts
+      #
+      def list(nzbn:)
+        response = @client.get("/entities/#{nzbn}/organisation-parts")
+        return [] unless response.is_a?(Array)
+
+        response.map { |op| Models::OrganisationPart.new(op) }
+      end
+
+      # Get an organisation part
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param opn [String] Organisation part number
+      # @return [Models::OrganisationPart] Organisation part details
+      #
+      def get(nzbn:, opn:)
+        response = @client.get("/entities/#{nzbn}/organisation-parts/#{opn}")
+        Models::OrganisationPart.new(response)
+      end
+
+      # Create an organisation part
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param organisation_part [Hash] Organisation part attributes
+      # @return [Models::OrganisationPart] Created organisation part
+      #
+      def create(nzbn:, organisation_part:)
+        response = @client.post("/entities/#{nzbn}/organisation-parts", organisation_part)
+        Models::OrganisationPart.new(response)
+      end
+
+      # Update an organisation part
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param opn [String] Organisation part number
+      # @param organisation_part [Hash] Updated attributes
+      # @return [Models::OrganisationPart] Updated organisation part
+      #
+      def update(nzbn:, opn:, organisation_part:)
+        response = @client.put("/entities/#{nzbn}/organisation-parts/#{opn}", organisation_part)
+        Models::OrganisationPart.new(response)
+      end
+
+      # Get GLN allocation summary for an entity
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Hash] Allocation summary
+      #
+      def gln_allocation(nzbn:)
+        @client.get("/entities/#{nzbn}/organisation-parts/allocation")
+      end
+    end
+  end
+end

data/lib/nzbn/api/phone_numbers.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Api
+    # Phone Numbers API
+    class PhoneNumbers
+      def initialize(client)
+        @client = client
+      end
+
+      # List phone numbers for an entity
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Models::PhoneNumber>] List of phone numbers
+      #
+      def list(nzbn:)
+        response = @client.get("/entities/#{nzbn}/phone-numbers")
+        return [] unless response.is_a?(Array)
+
+        response.map { |pn| Models::PhoneNumber.new(pn) }
+      end
+
+      # Add a phone number
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param phone [Hash] Phone number attributes
+      # @return [Models::PhoneNumber] Created phone number
+      #
+      def create(nzbn:, phone:)
+        response = @client.post("/entities/#{nzbn}/phone-numbers", phone)
+        Models::PhoneNumber.new(response)
+      end
+    end
+  end
+end

data/lib/nzbn/api/privacy_settings.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Api
+    # Privacy Settings API
+    class PrivacySettings
+      def initialize(client)
+        @client = client
+      end
+
+      # Get privacy settings for an entity
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Models::PrivacySettings] Privacy settings
+      #
+      def get(nzbn:)
+        response = @client.get("/entities/#{nzbn}/privacy-settings")
+        Models::PrivacySettings.new(response)
+      end
+
+      # Update privacy settings
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param settings [Hash] Privacy settings to update
+      # @return [Models::PrivacySettings] Updated settings
+      #
+      def update(nzbn:, settings:)
+        response = @client.put("/entities/#{nzbn}/privacy-settings", settings)
+        Models::PrivacySettings.new(response)
+      end
+    end
+  end
+end

data/lib/nzbn/api/roles.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Api
+    # Roles API - Manage entity roles (directors, partners, etc.)
+    class Roles
+      def initialize(client)
+        @client = client
+      end
+
+      # List roles for an entity
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Models::Role>] List of roles
+      #
+      def list(nzbn:)
+        response = @client.get("/entities/#{nzbn}/roles")
+        return [] unless response.is_a?(Array)
+
+        response.map { |role| Models::Role.new(role) }
+      end
+
+      # Add a role to an entity
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param role [Hash] Role attributes including roleType, rolePerson, etc.
+      # @return [Models::Role] Created role
+      #
+      # @example
+      #   client.roles.create(nzbn: '9429041925676', role: {
+      #     roleType: 'PARTNER_INDIVIDUAL',
+      #     rolePerson: { firstName: 'John', lastName: 'Doe' },
+      #     startDate: '2024-01-01'
+      #   })
+      #
+      def create(nzbn:, role:)
+        response = @client.post("/entities/#{nzbn}/roles", role)
+        Models::Role.new(response)
+      end
+
+      # Update a role
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param role [Hash] Updated role attributes
+      # @return [Models::Role] Updated role
+      #
+      def update(nzbn:, role:)
+        response = @client.put("/entities/#{nzbn}/roles", role)
+        Models::Role.new(response)
+      end
+    end
+  end
+end

data/lib/nzbn/api/trading_names.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Api
+    # Trading Names API
+    class TradingNames
+      def initialize(client)
+        @client = client
+      end
+
+      # List trading names for an entity
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Models::TradingName>] List of trading names
+      #
+      def list(nzbn:)
+        response = @client.get("/entities/#{nzbn}/trading-names")
+        return [] unless response.is_a?(Array)
+
+        response.map { |tn| Models::TradingName.new(tn) }
+      end
+
+      # Add a trading name
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param trading_name [Hash] Trading name attributes
+      # @return [Models::TradingName] Created trading name
+      #
+      def create(nzbn:, trading_name:)
+        response = @client.post("/entities/#{nzbn}/trading-names", trading_name)
+        Models::TradingName.new(response)
+      end
+    end
+  end
+end

data/lib/nzbn/api/watchlists.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Api
+    # Watchlists API - Manage change notification watchlists
+    class Watchlists
+      def initialize(client)
+        @client = client
+      end
+
+      # List watchlists
+      #
+      # @param name [String] Filter by name (partial match)
+      # @param organisation_id [String] Filter by organisation ID
+      # @param page [Integer] Page number
+      # @param page_size [Integer] Results per page
+      # @param sort_by [String] Sort field
+      # @param sort_order [String] ASC or DESC
+      # @param change_event_types [String] Filter by change event types
+      # @return [Models::SearchResponse] Paginated watchlist results
+      #
+      def list(name: nil, organisation_id: nil, page: nil, page_size: nil,
+               sort_by: nil, sort_order: nil, change_event_types: nil)
+        params = {}
+        params['name'] = name if name
+        params['organisation-id'] = organisation_id if organisation_id
+        params['page'] = page if page
+        params['page-size'] = page_size if page_size
+        params['sort-by'] = sort_by if sort_by
+        params['sortorder'] = sort_order if sort_order
+        params['change-event-types'] = change_event_types if change_event_types
+
+        response = @client.get('/watchlists', params)
+        Models::SearchResponse.new(response, item_class: Models::Watchlist)
+      end
+
+      # Get a watchlist by ID
+      #
+      # @param watchlist_id [String] Watchlist ID
+      # @return [Models::Watchlist] Watchlist details
+      #
+      def get(watchlist_id:)
+        response = @client.get("/watchlists/#{watchlist_id}")
+        Models::Watchlist.new(response)
+      end
+
+      # Create a new watchlist
+      #
+      # @param watchlist [Hash] Watchlist attributes
+      # @return [Models::Watchlist] Created watchlist
+      #
+      # @example
+      #   client.watchlists.create(watchlist: {
+      #     name: 'My Watchlist',
+      #     channel: 'EMAIL',
+      #     frequency: 'DAILY',
+      #     changeEventTypes: 'ALL',
+      #     adminEmailAddress: 'admin@example.com'
+      #   })
+      #
+      def create(watchlist:)
+        response = @client.post('/watchlists', watchlist)
+        Models::Watchlist.new(response)
+      end
+
+      # Update a watchlist
+      #
+      # @param watchlist_id [String] Watchlist ID
+      # @param watchlist [Hash] Updated watchlist attributes
+      # @return [Models::Watchlist] Updated watchlist
+      #
+      def update(watchlist_id:, watchlist:)
+        response = @client.put("/watchlists/#{watchlist_id}", watchlist)
+        Models::Watchlist.new(response)
+      end
+
+      # Delete a watchlist
+      #
+      # @param watchlist_id [String] Watchlist ID
+      # @return [Boolean] True if successful
+      #
+      def delete(watchlist_id:)
+        @client.delete("/watchlists/#{watchlist_id}")
+        true
+      end
+
+      # List NZBNs in a watchlist
+      #
+      # @param watchlist_id [String] Watchlist ID
+      # @return [Array<String>] List of NZBNs
+      #
+      def list_nzbns(watchlist_id:)
+        response = @client.get("/watchlists/#{watchlist_id}/nzbns")
+        response['nzbns'] || []
+      end
+
+      # Add NZBNs to a watchlist
+      #
+      # @param watchlist_id [String] Watchlist ID
+      # @param nzbns [Array<String>] NZBNs to add
+      # @return [Boolean] True if successful
+      #
+      def add_nzbns(watchlist_id:, nzbns:)
+        @client.post("/watchlists/#{watchlist_id}/nzbns", { nzbns: nzbns })
+        true
+      end
+
+      # Remove NZBNs from a watchlist
+      #
+      # @param watchlist_id [String] Watchlist ID
+      # @param nzbns [Array<String>] NZBNs to remove
+      # @return [Boolean] True if successful
+      #
+      def remove_nzbns(watchlist_id:, nzbns:)
+        @client.delete("/watchlists/#{watchlist_id}/nzbns", { nzbns: nzbns })
+        true
+      end
+    end
+  end
+end

data/lib/nzbn/api/websites.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Api
+    # Websites API
+    class Websites
+      def initialize(client)
+        @client = client
+      end
+
+      # List websites for an entity
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Models::Website>] List of websites
+      #
+      def list(nzbn:)
+        response = @client.get("/entities/#{nzbn}/websites")
+        return [] unless response.is_a?(Array)
+
+        response.map { |ws| Models::Website.new(ws) }
+      end
+
+      # Add a website
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param website [Hash] Website attributes
+      # @return [Models::Website] Created website
+      #
+      def create(nzbn:, website:)
+        response = @client.post("/entities/#{nzbn}/websites", website)
+        Models::Website.new(response)
+      end
+    end
+  end
+end

data/lib/nzbn/client.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/multipart'
+require 'json'
+require 'securerandom'
+
+module Nzbn
+  # Main HTTP client for NZBN API
+  #
+  # @example
+  #   client = Nzbn::Client.new
+  #   client.entities.search(search_term: 'Company Name')
+  #
+  class Client
+    attr_reader :configuration
+
+    def initialize(api_key: nil, base_url: nil, timeout: nil)
+      @configuration = Nzbn.configuration&.dup || Configuration.new
+      @configuration.api_key = api_key if api_key
+      @configuration.base_url = base_url if base_url
+      @configuration.timeout = timeout if timeout
+
+      validate_configuration!
+    end
+
+    # API Resource Accessors
+
+    def entities
+      @entities ||= Api::Entities.new(self)
+    end
+
+    def addresses
+      @addresses ||= Api::Addresses.new(self)
+    end
+
+    def roles
+      @roles ||= Api::Roles.new(self)
+    end
+
+    def trading_names
+      @trading_names ||= Api::TradingNames.new(self)
+    end
+
+    def phone_numbers
+      @phone_numbers ||= Api::PhoneNumbers.new(self)
+    end
+
+    def email_addresses
+      @email_addresses ||= Api::EmailAddresses.new(self)
+    end
+
+    def websites
+      @websites ||= Api::Websites.new(self)
+    end
+
+    def industry_classifications
+      @industry_classifications ||= Api::IndustryClassifications.new(self)
+    end
+
+    def privacy_settings
+      @privacy_settings ||= Api::PrivacySettings.new(self)
+    end
+
+    def company_details
+      @company_details ||= Api::CompanyDetails.new(self)
+    end
+
+    def watchlists
+      @watchlists ||= Api::Watchlists.new(self)
+    end
+
+    def organisation_parts
+      @organisation_parts ||= Api::OrganisationParts.new(self)
+    end
+
+    def history
+      @history ||= Api::History.new(self)
+    end
+
+    # HTTP Methods
+
+    def get(path, params = {}, headers = {})
+      request(:get, path, params, headers)
+    end
+
+    def post(path, body = {}, headers = {})
+      request(:post, path, body, headers)
+    end
+
+    def put(path, body = {}, headers = {})
+      request(:put, path, body, headers)
+    end
+
+    def patch(path, body = {}, headers = {})
+      request(:patch, path, body, headers)
+    end
+
+    def delete(path, params = {}, headers = {})
+      request(:delete, path, params, headers)
+    end
+
+    private
+
+    def validate_configuration!
+      return if configuration.valid?
+
+      raise ConfigurationError, 'API key is required. Configure with Nzbn.configure or pass api_key to Client.new'
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: configuration.base_url) do |conn|
+        conn.request :json
+        conn.response :json, content_type: /\bjson$/
+        conn.adapter Faraday.default_adapter
+
+        conn.options.timeout = configuration.timeout
+        conn.options.open_timeout = configuration.open_timeout
+
+        if configuration.logger
+          conn.response :logger, configuration.logger
+        end
+      end
+    end
+
+    def request(method, path, data, headers)
+      request_id = SecureRandom.uuid
+
+      merged_headers = default_headers(request_id).merge(headers)
+
+      response = connection.public_send(method) do |req|
+        req.url path
+        req.headers = merged_headers
+
+        case method
+        when :get, :delete
+          req.params = data unless data.empty?
+        else
+          req.body = data
+        end
+      end
+
+      handle_response(response)
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, "Request timed out: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    end
+
+    def default_headers(request_id)
+      {
+        'Ocp-Apim-Subscription-Key' => configuration.api_key,
+        'api-business-govt-nz-Request-Id' => request_id,
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json'
+      }
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response.body
+      when 400
+        raise ValidationError.new(response: response.body, status: response.status)
+      when 401
+        raise AuthenticationError.new('Authentication failed', response: response.body, status: response.status)
+      when 403
+        raise AuthorizationError.new('Authorization denied', response: response.body, status: response.status)
+      when 404
+        raise NotFoundError.new('Resource not found', response: response.body, status: response.status)
+      when 412
+        raise PreconditionFailedError.new('Precondition failed', response: response.body, status: response.status)
+      when 500..599
+        raise ServerError.new('Server error', response: response.body, status: response.status)
+      else
+        raise ApiError.new("Unexpected response: #{response.status}", response: response.body, status: response.status)
+      end
+    end
+  end
+end

data/lib/nzbn/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Nzbn
+  # Configuration class for NZBN client settings
+  #
+  # @example
+  #   Nzbn.configure do |config|
+  #     config.api_key = 'your-api-key'
+  #     config.base_url = 'https://api.business.govt.nz/gateway/nzbn/v5'
+  #     config.timeout = 30
+  #   end
+  #
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout, :open_timeout, :logger
+
+    def initialize
+      @api_key = nil
+      @base_url = Nzbn::DEFAULT_BASE_URL
+      @timeout = 30
+      @open_timeout = 10
+      @logger = nil
+    end
+
+    def valid?
+      !api_key.nil? && !api_key.empty?
+    end
+  end
+end

data/lib/nzbn/error.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Nzbn
+  # Base error class for NZBN client
+  class Error < StandardError
+    attr_reader :response, :code
+
+    def initialize(message = nil, response: nil, code: nil)
+      @response = response
+      @code = code
+      super(message)
+    end
+  end
+
+  # API error with status code and response body
+  class ApiError < Error
+    attr_reader :status, :error_code, :error_description, :errors
+
+    def initialize(message = nil, response: nil, status: nil)
+      @status = status
+      parse_response(response) if response
+      super(message || @error_description || 'API Error', response: response, code: @error_code)
+    end
+
+    private
+
+    def parse_response(response)
+      return unless response.is_a?(Hash)
+
+      @error_code = response['errorCode']
+      @error_description = response['errorDescription']
+      @errors = response['list'] || []
+    end
+  end
+
+  # 400 Bad Request - Validation errors
+  class ValidationError < ApiError; end
+
+  # 401 Unauthorized - Authentication required
+  class AuthenticationError < ApiError; end
+
+  # 403 Forbidden - Authorization denied
+  class AuthorizationError < ApiError; end
+
+  # 404 Not Found
+  class NotFoundError < ApiError; end
+
+  # 412 Precondition Failed - ETag mismatch
+  class PreconditionFailedError < ApiError; end
+
+  # 500 Internal Server Error
+  class ServerError < ApiError; end
+
+  # Connection/network errors
+  class ConnectionError < Error; end
+
+  # Timeout errors
+  class TimeoutError < Error; end
+
+  # Configuration errors
+  class ConfigurationError < Error; end
+end

data/lib/nzbn/models/address.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Models
+    # Address model
+    class Address < Base
+      attr_accessor :unique_identifier, :start_date, :end_date,
+                    :care_of, :address1, :address2, :address3, :address4,
+                    :post_code, :country_code, :address_type, :paf_id, :description
+    end
+  end
+end