nzbn-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e7eac967040c3029d0acea2032ebca30831db0521880a7469eac5c6f564ce5f9
+  data.tar.gz: d4c4d5c37dd025ea98c0cdba5c96c2e6c5d53d913b1fbd1e498b4ebd87ac0f0e
+SHA512:
+  metadata.gz: 997a10045c90eb5b971feade345d43602ca0c16fc73ae9c2b768ab62642f329261ca5e4eb8cc8d1ac71daf44c64df6416c2a397f1e1eb0f65cd2218bcf8e4888
+  data.tar.gz: 4d67960d1de75c27fe8fd9ad7040e304a7426a3ce14211b013dc1abb0feaf1f8452d9dd093482585f930b4c6496b86ba38a76a90bcce8412ce47018f937dd8e9

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-02-04
+
+### Added
+- Initial release
+- Entity search and retrieval
+- Entity creation (sole trader, partnership, trust)
+- Address management
+- Role management (directors, partners, trustees)
+- Trading names management
+- Phone numbers management
+- Email addresses management
+- Websites management
+- Industry classifications management
+- Privacy settings management
+- Company and non-company details
+- Watchlist management for change notifications
+- Organisation parts (OPN/GLN) management
+- Historical data access
+- Full error handling with custom exceptions

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nhan Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,239 @@
+# NZBN Ruby
+
+A Ruby gem for interacting with the New Zealand Business Number (NZBN) API v5.
+
+[![Gem Version](https://badge.fury.io/rb/nzbn-ruby.svg)](https://badge.fury.io/rb/nzbn-ruby)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'nzbn-ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install nzbn-ruby
+```
+
+## Requirements
+
+- ...
+
+## Configuration
+
+Configure the gem with your NZBN API key (obtain from [api.business.govt.nz](https://api.business.govt.nz)):
+
+```ruby
+Nzbn.configure do |config|
+  config.api_key = 'your-api-key'
+  config.base_url = 'https://api.business.govt.nz/gateway/nzbn/v5'  # default
+  config.timeout = 30  # optional, default 30 seconds
+end
+```
+
+## Usage
+
+### Initialize the Client
+
+```ruby
+client = Nzbn::Client.new
+
+# Or with inline configuration
+client = Nzbn::Client.new(api_key: 'your-api-key')
+```
+
+### Search Entities
+
+```ruby
+# Search by name
+results = client.entities.search(search_term: 'Company Name')
+
+results.each do |entity|
+  puts "#{entity.entity_name} (#{entity.nzbn})"
+end
+
+# With filters
+results = client.entities.search(
+  search_term: 'Wellington',
+  entity_status: 'Registered',
+  entity_type: 'NZCompany',
+  page: 0,
+  page_size: 20
+)
+```
+
+### Get Entity Details
+
+```ruby
+entity = client.entities.get(nzbn: '9429041925676')
+
+puts entity.entity_name
+puts entity.entity_status_description
+puts entity.registration_date
+```
+
+### Entity Change History
+
+```ruby
+# Search for changes
+changes = client.entities.changes(
+  change_event_type: 'ALL',
+  date_time_from: '2024-01-01T00:00:00',
+  date_time_to: '2024-12-31T23:59:59'
+)
+```
+
+### Manage Addresses
+
+```ruby
+# List addresses
+addresses = client.addresses.list(nzbn: '9429041925676')
+
+# Add an address
+new_address = client.addresses.create(
+  nzbn: '9429041925676',
+  address: {
+    addressType: 'POSTAL',
+    address1: '123 Main Street',
+    address2: 'Wellington',
+    postCode: '6011',
+    countryCode: 'NZ'
+  }
+)
+```
+
+### Manage Roles
+
+```ruby
+# List roles (directors, partners, etc.)
+roles = client.roles.list(nzbn: '9429041925676')
+
+roles.each do |role|
+  puts "#{role.role_type}: #{role.role_person&.first_name} #{role.role_person&.last_name}"
+end
+```
+
+### Trading Names
+
+```ruby
+trading_names = client.trading_names.list(nzbn: '9429041925676')
+```
+
+### Watchlists
+
+```ruby
+# Create a watchlist for change notifications
+watchlist = client.watchlists.create(watchlist: {
+  name: 'My Watchlist',
+  channel: 'EMAIL',
+  frequency: 'DAILY',
+  changeEventTypes: 'ALL',
+  adminEmailAddress: 'admin@example.com'
+})
+
+# Add NZBNs to watch
+client.watchlists.add_nzbns(
+  watchlist_id: watchlist.watchlist_id,
+  nzbns: ['9429041925676', '9429000001234']
+)
+
+# List watchlists
+my_watchlists = client.watchlists.list
+```
+
+### Privacy Settings
+
+```ruby
+# Get privacy settings
+settings = client.privacy_settings.get(nzbn: '9429041925676')
+
+# Update privacy settings
+client.privacy_settings.update(
+  nzbn: '9429041925676',
+  settings: { phonePrivateInformation: true }
+)
+```
+
+### Company Details
+
+```ruby
+# Get company-specific details
+company = client.company_details.get(nzbn: '9429041925676')
+
+puts company.annual_return_filing_month
+puts company.has_constitution_filed
+```
+
+### History
+
+```ruby
+# Get historical data
+historical_names = client.history.entity_names(nzbn: '9429041925676')
+historical_addresses = client.history.addresses(nzbn: '9429041925676')
+```
+
+## Error Handling
+
+```ruby
+begin
+  entity = client.entities.get(nzbn: 'invalid')
+rescue Nzbn::NotFoundError => e
+  puts "Entity not found"
+rescue Nzbn::AuthenticationError => e
+  puts "Invalid API key"
+rescue Nzbn::ValidationError => e
+  puts "Invalid request: #{e.message}"
+  e.errors.each { |err| puts "  #{err['field']}: #{err['message']}" }
+rescue Nzbn::ApiError => e
+  puts "API error: #{e.message} (#{e.error_code})"
+end
+```
+
+## API Resources
+
+| Resource | Description |
+|----------|-------------|
+| `entities` | Search, get, create entities |
+| `addresses` | Manage entity addresses |
+| `roles` | Manage directors, partners, etc. |
+| `trading_names` | Manage trading names |
+| `phone_numbers` | Manage phone numbers |
+| `email_addresses` | Manage email addresses |
+| `websites` | Manage websites |
+| `industry_classifications` | Manage ANZSIC codes |
+| `privacy_settings` | Manage privacy settings |
+| `company_details` | Get company/non-company details |
+| `watchlists` | Manage change notification watchlists |
+| `organisation_parts` | Manage OPN/GLN |
+| `history` | Access historical data |
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Links
+
+- [NZBN API Documentation](https://api.business.govt.nz/api/nzbn)
+- [API Explorer](https://api.business.govt.nz)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/nzbn/api/addresses.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Api
+    # Addresses API - Manage entity addresses
+    class Addresses
+      def initialize(client)
+        @client = client
+      end
+
+      # List addresses for an entity
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Models::Address>] List of addresses
+      #
+      def list(nzbn:)
+        response = @client.get("/entities/#{nzbn}/addresses")
+        parse_addresses(response)
+      end
+
+      # Add an address to an entity
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param address [Hash] Address attributes
+      # @return [Models::Address] Created address
+      #
+      # @example
+      #   client.addresses.create(nzbn: '9429041925676', address: {
+      #     addressType: 'POSTAL',
+      #     address1: '123 Main St',
+      #     address2: 'Wellington',
+      #     postCode: '6011',
+      #     countryCode: 'NZ'
+      #   })
+      #
+      def create(nzbn:, address:)
+        response = @client.post("/entities/#{nzbn}/addresses", address)
+        Models::Address.new(response)
+      end
+
+      # Delete an address from an entity
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param address_id [String] Unique identifier of the address
+      # @return [Boolean] True if successful
+      #
+      def delete(nzbn:, address_id:)
+        @client.delete("/entities/#{nzbn}/addresses", { uniqueIdentifier: address_id })
+        true
+      end
+
+      private
+
+      def parse_addresses(response)
+        return [] unless response.is_a?(Hash) && response['addressList']
+
+        response['addressList'].map { |addr| Models::Address.new(addr) }
+      end
+    end
+  end
+end

data/lib/nzbn/api/company_details.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Api
+    # Company Details API
+    class CompanyDetails
+      def initialize(client)
+        @client = client
+      end
+
+      # Get company details
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Models::Company] Company details
+      #
+      def get(nzbn:)
+        response = @client.get("/entities/#{nzbn}/company-details")
+        Models::Company.new(response)
+      end
+
+      # Get non-company details (limited partnerships, charities, etc.)
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Models::NonCompany] Non-company details
+      #
+      def get_non_company(nzbn:)
+        response = @client.get("/entities/#{nzbn}/non-company-details")
+        Models::NonCompany.new(response)
+      end
+    end
+  end
+end

data/lib/nzbn/api/email_addresses.rb

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

data/lib/nzbn/api/entities.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Api
+    # Entities API - Search and manage NZBN entities
+    class Entities
+      def initialize(client)
+        @client = client
+      end
+
+      # Search entities by name
+      #
+      # @param search_term [String] Text to search for
+      # @param entity_status [String] Filter by status (Registered, InLiquidation, etc.)
+      # @param entity_type [String] Filter by type (NZCompany, SoleTrader, etc.)
+      # @param industry_code [String] Filter by industry code
+      # @param page [Integer] Page number (zero-indexed)
+      # @param page_size [Integer] Results per page
+      # @return [Models::SearchResponse] Paginated search results
+      #
+      # @example
+      #   client.entities.search(search_term: 'Company Name', entity_status: 'Registered')
+      #
+      def search(search_term:, entity_status: nil, entity_type: nil, industry_code: nil, page: nil, page_size: nil)
+        params = { 'search-term' => search_term }
+        params['entity-status'] = entity_status if entity_status
+        params['entity-type'] = entity_type if entity_type
+        params['industry-code'] = industry_code if industry_code
+        params['page'] = page if page
+        params['page-size'] = page_size if page_size
+
+        response = @client.get('/entities', params)
+        Models::SearchResponse.new(response, item_class: Models::SearchEntity)
+      end
+
+      # Get entity by NZBN
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param if_none_match [String] ETag for conditional request
+      # @return [Models::FullEntity] Full entity details
+      #
+      # @example
+      #   entity = client.entities.get(nzbn: '9429041925676')
+      #
+      def get(nzbn:, if_none_match: nil)
+        headers = {}
+        headers['If-None-Match'] = if_none_match if if_none_match
+
+        response = @client.get("/entities/#{nzbn}", {}, headers)
+        Models::FullEntity.new(response)
+      end
+
+      # Get discoverable entity information
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Models::Entity] Discoverable entity info
+      #
+      def get_discoverable(nzbn:)
+        response = @client.get("/entities/#{nzbn}/discoverable")
+        Models::Entity.new(response)
+      end
+
+      # Search entity changes
+      #
+      # @param change_event_type [String] Comma-separated change events (NEW, ENTITY, ROLES_DIRECTOR, etc.)
+      # @param entity_type [String] Filter by entity type
+      # @param date_time_from [String] Start date (YYYY-MM-DDThh:mm:ss)
+      # @param date_time_to [String] End date (YYYY-MM-DDThh:mm:ss)
+      # @param page [Integer] Page number
+      # @param page_size [Integer] Results per page
+      # @param sort_by [String] Sort field (NZBN, ENTITY_NAME, etc.)
+      # @param sort_order [String] ASC or DESC
+      # @return [Models::SearchResponse] Change results
+      #
+      def changes(change_event_type:, entity_type: nil, date_time_from: nil, date_time_to: nil,
+                  page: nil, page_size: nil, sort_by: nil, sort_order: nil)
+        params = { 'change-event-type' => change_event_type }
+        params['entity-type'] = entity_type if entity_type
+        params['date-time-from'] = date_time_from if date_time_from
+        params['date-time-to'] = date_time_to if date_time_to
+        params['page'] = page if page
+        params['page-size'] = page_size if page_size
+        params['sort-by'] = sort_by if sort_by
+        params['sort-order'] = sort_order if sort_order
+
+        response = @client.get('/entities/changes', params)
+        Models::SearchResponse.new(response, item_class: Models::SearchEntity)
+      end
+
+      # Create a new entity (sole trader, partnership, or trust)
+      #
+      # @param entity [Hash] Entity attributes
+      # @return [Hash] Created entity response
+      #
+      def create(entity:)
+        @client.post('/entities', entity)
+      end
+
+      # Update entity status
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param status [Hash] Status update payload
+      # @return [Hash] Updated status
+      #
+      def update_status(nzbn:, status:)
+        @client.post("/entities/#{nzbn}/entity-statuses", status)
+      end
+
+      # Update Australian Business Number
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @param abn_data [Hash] ABN update payload
+      # @return [Hash] Updated ABN
+      #
+      def update_abn(nzbn:, abn_data:)
+        @client.put("/entities/#{nzbn}/australian-business-number", abn_data)
+      end
+    end
+  end
+end

data/lib/nzbn/api/history.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Nzbn
+  module Api
+    # History API - Access historical entity data
+    class History
+      def initialize(client)
+        @client = client
+      end
+
+      # Get entity change history
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Hash] Change history
+      #
+      def get(nzbn:)
+        @client.get("/entities/#{nzbn}/history")
+      end
+
+      # Get address history
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Models::Address>] Historical addresses
+      #
+      def addresses(nzbn:)
+        response = @client.get("/entities/#{nzbn}/history/addresses")
+        return [] unless response.is_a?(Array)
+
+        response.map { |addr| Models::Address.new(addr) }
+      end
+
+      # Get entity name history
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Hash>] Historical entity names
+      #
+      def entity_names(nzbn:)
+        @client.get("/entities/#{nzbn}/history/entity-names")
+      end
+
+      # Get trading name history
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Models::TradingName>] Historical trading names
+      #
+      def trading_names(nzbn:)
+        response = @client.get("/entities/#{nzbn}/history/trading-names")
+        return [] unless response.is_a?(Array)
+
+        response.map { |tn| Models::TradingName.new(tn) }
+      end
+
+      # Get trading area history
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Hash>] Historical trading areas
+      #
+      def trading_areas(nzbn:)
+        @client.get("/entities/#{nzbn}/history/trading-areas")
+      end
+
+      # Get entity status history
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Hash>] Historical entity statuses
+      #
+      def entity_statuses(nzbn:)
+        @client.get("/entities/#{nzbn}/history/entity-statuses")
+      end
+
+      # Get hibernation status history
+      #
+      # @param nzbn [String] 13-digit NZBN
+      # @return [Array<Hash>] Historical hibernation statuses
+      #
+      def hibernation_statuses(nzbn:)
+        @client.get("/entities/#{nzbn}/history/hibernation-statuses")
+      end
+    end
+  end
+end

data/lib/nzbn/api/industry_classifications.rb

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