checkify 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1fb398a2b3bac9a1ef8b2093c1fe8122611de7d42ba9d53c0b05d2e65ef13129
+  data.tar.gz: 054d9fad13402d278031a748842987984164f46f3cb52a71c76c3868cde1d624
+SHA512:
+  metadata.gz: 6e43d7f516b7a591419dbdb834302c8a20f20842d423e659cfa9348f7271df494d0640ce863eb36c7fd1f33e40145dfc0cfbee2430539499760998bb643cb48a
+  data.tar.gz: 7559c9c422bb50c8ed3c4d7e4792b95cf1a5bd52ec5b6427147663823e064e7d219d665777c0b996473522d67cc0b25f325bd03c1059fbad62acdd136a2fedba

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (2026-09-05)
+
+- Initial Ruby client for Checkify's address, business, identity, communication, account, and bulk APIs.
+- Support JSON and CSV bulk submissions.
+- Offline VCR playback, opt-in production recording, and simulated bulk tests.
+- Ruby 3.3 or later; packaged files exclude local credentials, recordings, and development files.
+- Per-instance client with endpoint groups, a 30-second default timeout, and configurable redirect handling.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Caldwell
+
+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,319 @@
+# Checkify for Ruby
+
+Unofficial Ruby client for the [Checkify API](https://checkify.com.au/developers) — Australian and New Zealand address validation, business lookups, identity checks, and communication validation.
+
+## Installation
+
+Requires Ruby 3.3 or later and libcurl (normally included with macOS and Linux).
+
+Add to your Gemfile:
+
+```ruby
+gem "checkify", "~> 0.1.0"
+```
+
+Then run `bundle install`.
+
+## Configuration
+
+```ruby
+require "checkify"
+
+client = Checkify::Client.new(api_key: ENV.fetch("CHECKIFY_API_KEY"))
+```
+
+Each client has its own credentials and configuration. Requests time out after 30
+seconds by default; pass `timeout: 60` to change this (or `timeout: 0` to disable it).
+For advanced configuration, pass a block:
+
+```ruby
+client = Checkify::Client.new(api_key: ENV.fetch("CHECKIFY_API_KEY"), timeout: 60) do |config|
+  config.debugging = false
+end
+```
+
+Two token types are available — see the [Checkify docs](https://checkify.com.au/developers) for details:
+
+- **Public** (`ck_pub_...`) — safe for browser/mobile use, domain-restricted
+- **Private** (`ck_prv_...`) — server-side only, higher rate limits
+
+## Usage
+
+### Address autocomplete
+
+```ruby
+address_api = client.address
+
+# type-ahead search (free, 0 units)
+results = address_api.autocomplete("1 macquarie st sydney")
+# => a hash of address IDs to highlighted labels
+
+# full structured record (1 unit)
+details = address_api.autocomplete_details(results.keys.first)
+# => #<Checkify::AddressDetails street="1 MACQUARIE ST", city="SYDNEY", postcode="2000", ...>
+```
+
+### Suburb and postcode lookup
+
+```ruby
+# suburb autocomplete (free)
+suburbs = address_api.autocomplete_suburb("sydney")
+
+# full suburb details (1 unit)
+address_api.autocomplete_suburb_details(suburbs.keys.first)
+
+# all suburbs for a postcode (1 unit)
+address_api.postcode_lookup("2000")
+```
+
+### Reverse geocode
+
+```ruby
+address_api.reverse_geocode(-33.8688, 151.2130, radius: 200, limit: 3)
+```
+
+### ABN / ACN lookup
+
+```ruby
+business_api = client.business
+
+abn = business_api.abn_lookup("26 008 672 179")
+abn.entity_name    # => "BUNNINGS GROUP LIMITED"
+abn.abn_details.active  # => true
+
+acn = business_api.acn_lookup("008 672 179")
+acn.addresses      # => [#<Checkify::AcnAddress ...>, ...]
+acn.documents      # => [#<Checkify::AsicDocument ...>, ...]
+```
+
+### Business activity search
+
+```ruby
+business_api.business_activity("accounting", limit: 5)
+```
+
+### Company / business name availability
+
+```ruby
+business_api.company_name_check("Acme Holdings Pty Ltd")
+business_api.business_name_check("The Coffee Collective")
+```
+
+### Email validation
+
+```ruby
+comms_api = client.communication
+
+result = comms_api.email_validation("person@example.com")
+result.valid       # => true
+result.score       # => 0.48 (may be nil when unavailable)
+result.free        # => true
+result.disposable  # => false
+```
+
+### Phone validation
+
+```ruby
+result = comms_api.phone_validation("0412345678")
+result.phone       # => "+61412345678"
+result.country     # => "AU"
+result.type        # => "mobile"
+result.carrier     # => carrier name, when available
+```
+
+### Sanctions screening
+
+```ruby
+identity_api = client.identity
+
+result = identity_api.sanctions_screening("Mohammad Hassan", birth_year: 1950, country: "AF")
+result.match       # => true
+result.results.first.confidence  # => 0.848
+```
+
+### TFN / Director ID validation
+
+```ruby
+identity_api.tfn_validation("123456782")
+identity_api.director_id_validation("036123456789010")
+```
+
+### Account usage
+
+```ruby
+account_api = client.account
+account = account_api.get_account
+account.units_remaining  # => 48760
+account.usage            # => { "autocomplete" => 520, "abn" => 295, ... }
+```
+
+## Bulk processing
+
+Bulk processing requires an eligible Checkify subscription. JSON input accepts strings for
+single-field endpoints or objects for endpoints such as reverse geocoding:
+
+```ruby
+batch_api = client.batch
+job = batch_api.create_bulk_job(
+  Checkify::BulkCreateRequest.new(endpoint: "abn", items: ["26008672179"])
+)
+batch_api.get_bulk_job(job.id)
+```
+
+For CSV upload, supply the endpoint and an open file as multipart form parameters:
+
+```ruby
+File.open("businesses.csv", "rb") do |file|
+  job = batch_api.create_bulk_job(
+    {},
+    header_params: { "Content-Type" => "multipart/form-data" },
+    form_params: { "endpoint" => "abn", "file" => file }
+  )
+end
+```
+
+Once a job completes, download its results and clean up the temporary file:
+
+```ruby
+require "fileutils"
+
+file = batch_api.download_bulk_results(job.id)
+begin
+  FileUtils.cp(file.path, "results.csv")
+ensure
+  file.unlink
+end
+```
+
+## Error handling
+
+```ruby
+begin
+  result = business_api.abn_lookup("invalid")
+rescue Checkify::ApiError => e
+  e.code     # => 422
+  e.response_body # => JSON containing the server error
+  e.message       # => readable status, headers, and response body
+end
+```
+
+The generated classes remain available for lower-level use. Configure their shared
+defaults with `Checkify.configure`, or pass a `Checkify::ApiClient` constructed with
+its own `Checkify::Configuration` to an endpoint class. `Checkify::Client` does not
+change those shared defaults.
+
+Redirects are followed by default. Pass `follow_location: false` to an endpoint
+method to receive the redirect response as a `Checkify::ApiError` instead.
+
+## API endpoints
+
+All URIs are relative to `https://checkify.com.au/api/v1`.
+
+| Class | Method | Endpoint | Description |
+|---|---|---|---|
+| `AccountApi` | `get_account` | `GET /account` | Account details and usage |
+| `AddressApi` | `autocomplete` | `GET /autocomplete` | Address type-ahead search |
+| `AddressApi` | `autocomplete_details` | `GET /autocomplete-details` | Full structured address |
+| `AddressApi` | `autocomplete_suburb` | `GET /autocomplete-suburb` | Suburb type-ahead search |
+| `AddressApi` | `autocomplete_suburb_details` | `GET /autocomplete-suburb-details` | Full suburb details |
+| `AddressApi` | `postcode_lookup` | `GET /postcode` | Suburbs for a postcode |
+| `AddressApi` | `reverse_geocode` | `GET /reverse` | Nearest address to coordinates |
+| `BusinessApi` | `abn_lookup` | `GET /abn` | ABN validation and details |
+| `BusinessApi` | `acn_lookup` | `GET /acn` | ACN validation and details |
+| `BusinessApi` | `business_activity` | `GET /business-activity` | ANZSIC activity search |
+| `BusinessApi` | `business_name_check` | `GET /business-name` | Business name availability |
+| `BusinessApi` | `company_name_check` | `GET /company-name` | Company name availability |
+| `CommunicationApi` | `email_validation` | `GET /email` | Email validation |
+| `CommunicationApi` | `phone_validation` | `GET /phone` | Phone validation |
+| `IdentityApi` | `sanctions_screening` | `GET /sanctions-screening` | Sanctions list screening |
+| `IdentityApi` | `director_id_validation` | `GET /director-id` | Director ID checksum validation |
+| `IdentityApi` | `tfn_validation` | `GET /tfn` | TFN checksum validation |
+| `BatchApi` | `create_bulk_job` | `POST /bulk` | Submit bulk processing job |
+| `BatchApi` | `get_bulk_job` | `GET /bulk/{id}` | Check bulk job status |
+| `BatchApi` | `download_bulk_results` | `GET /bulk/{id}/download` | Download bulk results CSV |
+
+## Development
+
+```bash
+bundle install
+bundle exec rake
+bundle exec rubocop
+bundle exec rake build
+```
+
+The normal suite uses [VCR](https://github.com/vcr/vcr) to replay committed recordings
+from `spec/fixtures/cassettes`. It does not load `.env` or contact Checkify, and fails
+if a required recording is missing. The API recordings are genuine production
+responses. Business fixtures use [Bunnings Group Limited (ABN 26 008 672 179)](https://abr.business.gov.au/ABN/View/26008672179).
+Other examples use public addresses, Checkify's documented sample identifiers, and
+`person@example.com`. Bulk tests use explicitly simulated responses because the
+recording account does not have a bulk subscription; the multipart test verifies
+libcurl's actual HTTP upload against a local test server.
+
+### Recording against production
+
+Set `CHECKIFY_API_KEY` in your environment or a local `.env` file; `.env.example`
+shows the format. A private API key is recommended. Then explicitly enable recording:
+
+```bash
+CHECKIFY_RECORD=1 bundle exec rspec spec/api spec/api_client_spec.rb spec/client_spec.rb
+```
+
+This records missing interactions and replays existing ones. To refresh a particular
+recording, remove that cassette first:
+
+```bash
+rm spec/fixtures/cassettes/business/abn_lookup.yml
+CHECKIFY_RECORD=1 bundle exec rspec spec/api/business_api_spec.rb
+```
+
+To exercise the full recorded suite against production, remove `spec/fixtures/cassettes`
+first and run the recording command. Review the resulting diff before committing.
+Calls consume Checkify units and are paced below the free plan's rate limit. Bulk
+specs remain simulated in recording mode. Public business responses are retained;
+a recording hook removes credentials/cookies and redacts account usage and billing
+dates. Never hand-edit recordings to make tests pass: fix the test inputs or recording
+configuration, then record again. Old ignored files under `spec/cassettes` are unused.
+
+### Regenerating the client
+
+`openapi.yaml` is the locally maintained API contract, checked against
+[Checkify's reference](https://checkify.com.au/developers). No downloadable upstream
+OpenAPI document was available during the review on 5 September 2026.
+
+Install OpenAPI Generator **7.21.0** and Java, then run:
+
+```bash
+bundle exec rake generate
+bundle exec rake
+```
+
+`script/generate` uses `generator/config.yaml`, applies the multipart, redirect,
+and timeout fixes to the upstream Ruby templates, regenerates the generated files
+in `lib/` and `docs/`, and applies the project's lint rules. The handwritten
+`lib/checkify/client.rb`, tests, gemspec, README, and CI are preserved.
+Change the input spec or generator customization before regenerating; do not patch
+generated library files directly. Regeneration removes obsolete generated files;
+inspect the diff for removed or renamed schemas.
+
+### Release checks
+
+CI tests Ruby 3.3, 3.4, and 4.0, builds and loads the packaged gem, and scans Git history
+for credentials. Run the suite, lint, `gem build checkify.gemspec`, and
+`gitleaks git . --log-opts='--all' --redact` before publishing. The gem's explicit
+file list excludes tests, recordings, credentials, and local notes.
+
+Releases use [RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/)
+from `.github/workflows/release.yml` and the GitHub `release` environment. To release:
+
+1. Set `gemVersion` in `generator/config.yaml`, regenerate, and update the changelog.
+2. Commit the changes to `master` and wait for CI to pass.
+3. Tag that commit with the matching version (for example, `v0.1.0`) and push the tag.
+
+The release workflow reruns CI, verifies that the tag matches the gem version, and
+publishes to RubyGems. No RubyGems API key is stored in the repository. Published
+versions are immutable; subsequent changes need a new version and tag.
+
+## License
+
+This gem is available under the [MIT License](LICENSE).

data/docs/AbnAddress.md

@@ -0,0 +1,24 @@
+# Checkify::AbnAddress
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **type** | **String** | Address type (e.g. serviceAddress) | [optional] |
+| **state** | **String** |  | [optional] |
+| **postcode** | **String** |  | [optional] |
+| **active_from** | **Date** |  | [optional] |
+
+## Example
+
+```ruby
+require 'checkify'
+
+instance = Checkify::AbnAddress.new(
+  type: null,
+  state: null,
+  postcode: null,
+  active_from: null
+)
+```
+

data/docs/AbnResponse.md

@@ -0,0 +1,34 @@
+# Checkify::AbnResponse
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **abn** | **String** |  | [optional] |
+| **abn_formatted** | **String** |  | [optional] |
+| **acn** | **String** |  | [optional] |
+| **acn_formatted** | **String** |  | [optional] |
+| **entity_name** | **String** |  | [optional] |
+| **entity_type** | **String** |  | [optional] |
+| **abn_details** | [**AbnResponseAbnDetails**](AbnResponseAbnDetails.md) |  | [optional] |
+| **addresses** | [**Array<AbnAddress>**](AbnAddress.md) |  | [optional] |
+| **business_names** | **Array<String>** |  | [optional] |
+
+## Example
+
+```ruby
+require 'checkify'
+
+instance = Checkify::AbnResponse.new(
+  abn: null,
+  abn_formatted: null,
+  acn: null,
+  acn_formatted: null,
+  entity_name: null,
+  entity_type: null,
+  abn_details: null,
+  addresses: null,
+  business_names: null
+)
+```
+

data/docs/AbnResponseAbnDetails.md

@@ -0,0 +1,22 @@
+# Checkify::AbnResponseAbnDetails
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **active** | **Boolean** |  | [optional] |
+| **active_from** | **Date** |  | [optional] |
+| **gst** | **Date** | GST registration date | [optional] |
+
+## Example
+
+```ruby
+require 'checkify'
+
+instance = Checkify::AbnResponseAbnDetails.new(
+  active: null,
+  active_from: null,
+  gst: null
+)
+```
+

data/docs/Account.md

@@ -0,0 +1,36 @@
+# Checkify::Account
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **plan** | **String** |  | [optional] |
+| **plan_name** | **String** |  | [optional] |
+| **status** | **String** |  | [optional] |
+| **cancels_at** | **Date** | ISO 8601 date when subscription ends (only when status is cancelling) | [optional] |
+| **units_used** | **Integer** |  | [optional] |
+| **units_limit** | **Integer** |  | [optional] |
+| **units_remaining** | **Integer** |  | [optional] |
+| **period_start** | **Date** |  | [optional] |
+| **period_end** | **Date** |  | [optional] |
+| **usage** | **Hash<String, Integer>** | Per-endpoint call counts for the current period | [optional] |
+
+## Example
+
+```ruby
+require 'checkify'
+
+instance = Checkify::Account.new(
+  plan: null,
+  plan_name: null,
+  status: null,
+  cancels_at: null,
+  units_used: null,
+  units_limit: null,
+  units_remaining: null,
+  period_start: null,
+  period_end: null,
+  usage: null
+)
+```
+

data/docs/AccountApi.md

@@ -0,0 +1,74 @@
+# Checkify::AccountApi
+
+All URIs are relative to *https://checkify.com.au/api/v1*
+
+| Method | HTTP request | Description |
+| ------ | ------------ | ----------- |
+| [**get_account**](AccountApi.md#get_account) | **GET** /account | Get account details |
+
+
+## get_account
+
+> <Account> get_account
+
+Get account details
+
+Returns your current plan, unit usage, billing period, subscription status, and a per-endpoint breakdown of API calls for the current period. Costs 0 units. Usage breakdown is cached for 5 minutes. 
+
+### Examples
+
+```ruby
+require 'time'
+require 'checkify'
+# setup authorization
+Checkify.configure do |config|
+  # Configure Bearer authorization: BearerAuth
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = Checkify::AccountApi.new
+
+begin
+  # Get account details
+  result = api_instance.get_account
+  p result
+rescue Checkify::ApiError => e
+  puts "Error when calling AccountApi->get_account: #{e}"
+end
+```
+
+#### Using the get_account_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<Account>, Integer, Hash)> get_account_with_http_info
+
+```ruby
+begin
+  # Get account details
+  data, status_code, headers = api_instance.get_account_with_http_info
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <Account>
+rescue Checkify::ApiError => e
+  puts "Error when calling AccountApi->get_account_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+This endpoint does not need any parameter.
+
+### Return type
+
+[**Account**](Account.md)
+
+### Authorization
+
+[BearerAuth](../README.md#BearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+

data/docs/AcnAddress.md

@@ -0,0 +1,24 @@
+# Checkify::AcnAddress
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **type** | **String** | Address type (registeredOffice, principalPlaceOfBusiness) | [optional] |
+| **suburb** | **String** |  | [optional] |
+| **state** | **String** |  | [optional] |
+| **postcode** | **String** |  | [optional] |
+
+## Example
+
+```ruby
+require 'checkify'
+
+instance = Checkify::AcnAddress.new(
+  type: null,
+  suburb: null,
+  state: null,
+  postcode: null
+)
+```
+

data/docs/AcnResponse.md

@@ -0,0 +1,38 @@
+# Checkify::AcnResponse
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **abn** | **String** |  | [optional] |
+| **abn_formatted** | **String** |  | [optional] |
+| **acn** | **String** |  | [optional] |
+| **acn_formatted** | **String** |  | [optional] |
+| **entity_name** | **String** |  | [optional] |
+| **entity_type** | **String** |  | [optional] |
+| **abn_details** | [**AcnResponseAbnDetails**](AcnResponseAbnDetails.md) |  | [optional] |
+| **acn_details** | [**AcnResponseAcnDetails**](AcnResponseAcnDetails.md) |  | [optional] |
+| **addresses** | [**Array<AcnAddress>**](AcnAddress.md) |  | [optional] |
+| **former_names** | [**Array<FormerName>**](FormerName.md) |  | [optional] |
+| **documents** | [**Array<AsicDocument>**](AsicDocument.md) |  | [optional] |
+
+## Example
+
+```ruby
+require 'checkify'
+
+instance = Checkify::AcnResponse.new(
+  abn: null,
+  abn_formatted: null,
+  acn: null,
+  acn_formatted: null,
+  entity_name: null,
+  entity_type: null,
+  abn_details: null,
+  acn_details: null,
+  addresses: null,
+  former_names: null,
+  documents: null
+)
+```
+

data/docs/AcnResponseAbnDetails.md

@@ -0,0 +1,18 @@
+# Checkify::AcnResponseAbnDetails
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **active_from** | **Date** |  | [optional] |
+
+## Example
+
+```ruby
+require 'checkify'
+
+instance = Checkify::AcnResponseAbnDetails.new(
+  active_from: null
+)
+```
+

data/docs/AcnResponseAcnDetails.md

@@ -0,0 +1,22 @@
+# Checkify::AcnResponseAcnDetails
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **active** | **Boolean** |  | [optional] |
+| **active_from** | **Date** |  | [optional] |
+| **active_to** | **Date** |  | [optional] |
+
+## Example
+
+```ruby
+require 'checkify'
+
+instance = Checkify::AcnResponseAcnDetails.new(
+  active: null,
+  active_from: null,
+  active_to: null
+)
+```
+