postio 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ee5a074b8751e84901306fd99658973e1635f98761b1a6925a9b3c83d6a00454
+  data.tar.gz: d72f7607c25f2437d0f7436c9b503968a7c3d20f0584ba427365346fb8348649
+SHA512:
+  metadata.gz: e5bf796095c34ef9815140482ee8347d79aa747f39e173ca0ea5296d3d16c1cd7a25ad039fe947ddad598236b7be9f070ec6f648d455164be93342f12a9a8b25
+  data.tar.gz: 99e2f1d7221a697535bc165b636cbe683ca4ae41448757f0f43f3af821f8dea7bbf6e2aff3b3694c66c441d566ee4a54512265b443f9d02b69277c0e7cfb7028

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to `postio` are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versioning
+follows [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-02
+
+Initial release. First Postio Ruby SDK on RubyGems.
+
+### Added
+
+- `Postio::Client` (synchronous; Ruby's async story is fragmented and
+  SDK customers want blocking calls).
+- Address: `client.address.search/postcode/udprn`.
+- Email: `client.email.validate`.
+- Phone: `client.phone.validate`.
+- Health probe: `client.connect`.
+- Immutable `Data` value classes (Ruby 3.2+) for every response.
+- Typed error hierarchy: `Postio::Error` base + 9 subclasses
+  (`InvalidKeyError`, `OutOfCreditError`, `ForbiddenError`,
+  `NotFoundError`, `ValidationError`, `RateLimitError`, `ServerError`,
+  `TimeoutError`, `ConnectionError`). Each carries `status`,
+  `error_code`, `details`, `request_id`, `envelope`.
+- Default retry policy (2 retries, exp backoff + full jitter on
+  408/409/429/5xx + network/timeout). Mirrors `@postio/node`.
+- Stdlib `net/http` only — no runtime dependencies.
+- `POSTIO_API_KEY` env var fallback when `api_key:` is not passed.
+
+### Notes
+
+- `PhoneResult#is_reachable` is plain `Object` (untyped) because the
+  live API returns booleans there even though the spec says
+  string-only. Aligned once postio-api ships a spec/runtime fix.
+
+[Unreleased]: https://github.com/postio-uk/postio-ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/postio-uk/postio-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Onno Group Limited (trading as Postio)
+
+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,123 @@
+# Postio Ruby SDK
+
+[![Gem Version](https://img.shields.io/gem/v/postio.svg)](https://rubygems.org/gems/postio)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-red)](https://rubygems.org/gems/postio)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Ruby SDK for the [Postio API](https://postio.co.uk) — UK address, email, and
+phone validation. Backed by Royal Mail PAF and Ordnance Survey. Stdlib
+`net/http` only, zero runtime dependencies.
+
+## Install
+
+```bash
+gem install postio
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem "postio", "~> 0.1"
+```
+
+Requires Ruby 3.1+.
+
+## 30-second example
+
+```ruby
+require "postio"
+
+client = Postio::Client.new(api_key: "pk_live_...")  # or set POSTIO_API_KEY
+
+result = client.address.search("downing street")
+result.results.each do |hit|
+  puts "#{hit.udprn}: #{hit.suggestion}"
+end
+
+puts "request id: #{result.meta.request_id}"
+```
+
+## API
+
+| Method | Returns |
+|---|---|
+| `client.address.search(q, max_results:)` | `AddressSearchEnvelope` |
+| `client.address.postcode(postcode, max_results:)` | `AddressPostcodeEnvelope` |
+| `client.address.udprn(udprn)` | `AddressUdprnEnvelope` |
+| `client.email.validate(address)` | `EmailEnvelope` |
+| `client.phone.validate(number)` | `PhoneEnvelope` |
+| `client.connect` | `ConnectSuccess` |
+
+All response objects are immutable `Data` value classes (Ruby 3.2+).
+Field names are snake_case in Ruby; the API uses camelCase JSON.
+
+## Errors
+
+Every non-2xx response raises a typed error. `Postio::Error` is the base.
+
+```ruby
+begin
+  client.address.postcode("not-a-postcode")
+rescue Postio::ValidationError => e
+  puts "#{e.status} #{e.error_code}: #{e.message} (request_id: #{e.request_id})"
+rescue Postio::RateLimitError => e
+  puts "rate limited; retry in #{e.retry_after} seconds"
+end
+```
+
+| Class | HTTP |
+|---|---|
+| `Postio::ValidationError` | 400 / 422 |
+| `Postio::InvalidKeyError` | 401 |
+| `Postio::OutOfCreditError` | 402 |
+| `Postio::ForbiddenError` | 403 |
+| `Postio::NotFoundError` | 404 |
+| `Postio::RateLimitError` | 429 (`#retry_after`) |
+| `Postio::ServerError` | 5xx |
+| `Postio::TimeoutError` | local request timeout |
+| `Postio::ConnectionError` | transport error |
+
+Every error carries `status`, `error_code`, `details`, `request_id`, and
+the raw `envelope`.
+
+## Configuration
+
+```ruby
+client = Postio::Client.new(
+  api_key:  "pk_live_...",
+  base_url: "https://api.postio.co.uk/v1",  # default
+  timeout:  10,                              # seconds
+  retries:  2,                               # 0 to disable
+  headers:  { "x-tracking-id" => "..." }
+)
+```
+
+Default retry policy: 2 retries on 408/409/429/5xx + network/timeout,
+exponential backoff with full jitter (0.5s → 8s cap).
+
+## Frameworks
+
+The SDK is framework-agnostic. Cache one `Postio::Client` per process —
+it's safe for concurrent use under MRI / YJIT / Truffle.
+
+**Rails** — initialiser:
+
+```ruby
+# config/initializers/postio.rb
+POSTIO = Postio::Client.new(api_key: Rails.application.credentials.postio_api_key)
+```
+
+## Links
+
+- [Docs](https://postio.co.uk/docs)
+- [API reference (OpenAPI)](https://postio.co.uk/openapi.json)
+- [Changelog](./CHANGELOG.md)
+- [Issues](https://github.com/postio-uk/postio-ruby/issues)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+> *Postio is a trading name of Onno Group Limited, registered in
+> England & Wales (company no. 08622799). Registered office:
+> Suite 22 Trym Lodge, 1 Henbury Road, Westbury-On-Trym, Bristol BS9 3HQ.*

data/lib/postio/client.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "version"
+require_relative "errors"
+require_relative "models"
+
+module Postio
+  # Postio::Client is the synchronous Postio API client.
+  #
+  # Example:
+  #
+  #   client = Postio::Client.new(api_key: "pk_live_...")
+  #   r = client.address.search("downing street")
+  #   r.results.each { |hit| puts "#{hit.udprn}: #{hit.suggestion}" }
+  #
+  # The API key may also come from the POSTIO_API_KEY environment
+  # variable.
+  class Client
+    DEFAULT_BASE_URL = "https://api.postio.co.uk/v1"
+    DEFAULT_TIMEOUT  = 10
+    RETRYABLE_STATUSES = [408, 409, 429, 500, 502, 503, 504].freeze
+
+    attr_reader :address, :email, :phone
+
+    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                   retries: 2, headers: {})
+      @api_key = api_key || ENV["POSTIO_API_KEY"]
+      raise ArgumentError, "Postio: api_key is required (pass api_key: ... or set POSTIO_API_KEY)" if @api_key.nil? || @api_key.empty?
+
+      @base_url       = base_url.chomp("/")
+      @timeout        = timeout
+      @retries        = retries
+      @extra_headers  = headers
+
+      @address = AddressResource.new(self)
+      @email   = EmailResource.new(self)
+      @phone   = PhoneResource.new(self)
+    end
+
+    # Health probe — confirms the API is reachable and the key is valid.
+    def connect
+      Models::ConnectSuccess.from_hash(request("/connect"))
+    end
+
+    # @api private — used by resource classes.
+    def request(path, query: {})
+      uri = URI(@base_url + path)
+      params = query.compact.transform_values(&:to_s)
+      uri.query = URI.encode_www_form(params) unless params.empty?
+
+      max_attempts = @retries + 1
+      last_error   = nil
+
+      max_attempts.times do |attempt|
+        begin
+          response = perform_http(uri)
+        rescue Net::OpenTimeout, Net::ReadTimeout => e
+          last_error = TimeoutError.new("Request timed out.", error_code: "request_timeout", cause: e)
+          raise last_error if attempt == max_attempts - 1
+
+          sleep(backoff(attempt))
+          next
+        rescue StandardError => e
+          last_error = ConnectionError.new("Network error: #{e.message}", error_code: "network_error", cause: e)
+          raise last_error if attempt == max_attempts - 1
+
+          sleep(backoff(attempt))
+          next
+        end
+
+        body = parse_body(response)
+
+        if response.is_a?(Net::HTTPSuccess)
+          return body
+        end
+
+        # Non-2xx — retryable status?
+        if RETRYABLE_STATUSES.include?(response.code.to_i) && attempt < max_attempts - 1
+          last_error = build_error(response, body)
+          sleep(backoff(attempt))
+          next
+        end
+
+        raise build_error(response, body)
+      end
+
+      # Unreachable — loop above either returns or raises.
+      raise(last_error || Error.new("Postio: retry loop exhausted unexpectedly."))
+    end
+
+    private
+
+    def perform_http(uri)
+      req = Net::HTTP::Get.new(uri.request_uri)
+      req["x-api-key"]        = @api_key
+      req["Accept"]           = "application/json"
+      req["User-Agent"]       = "postio-ruby/#{VERSION}"
+      req["x-postio-client"]  = "postio-ruby/#{VERSION}"
+      @extra_headers.each { |k, v| req[k] = v }
+
+      Net::HTTP.start(uri.hostname, uri.port,
+                      use_ssl: uri.scheme == "https",
+                      open_timeout: @timeout,
+                      read_timeout: @timeout) do |http|
+        http.request(req)
+      end
+    end
+
+    def parse_body(response)
+      content_type = (response["content-type"] || "").to_s
+      unless content_type.include?("application/json")
+        raise Error.new(
+          "Unexpected response content-type: #{content_type.inspect}",
+          status: response.code.to_i,
+          error_code: "unexpected_content_type",
+          details: response.body[0, 500]
+        )
+      end
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError => e
+      raise Error.new("Failed to parse response body as JSON.",
+                      status: response.code.to_i,
+                      error_code: "parse_error",
+                      cause: e)
+    end
+
+    def build_error(response, envelope)
+      status     = response.code.to_i
+      error      = envelope.is_a?(Hash) ? envelope["error"] : nil
+      details    = envelope.is_a?(Hash) ? envelope["details"] : nil
+      request_id = envelope.dig("meta", "requestId") if envelope.is_a?(Hash)
+      message    = (error || "HTTP #{status}").to_s
+
+      klass = Postio.error_class_for(status)
+      kwargs = {
+        status:     status,
+        error_code: error,
+        details:    details,
+        request_id: request_id,
+        envelope:   envelope.is_a?(Hash) ? envelope : nil
+      }
+
+      if klass == RateLimitError
+        retry_after_header = response["retry-after"]
+        retry_after = retry_after_header && retry_after_header.match?(/\A\d+(\.\d+)?\z/) ? retry_after_header.to_f : nil
+        return RateLimitError.new(message, retry_after: retry_after, **kwargs)
+      end
+
+      klass.new(message, **kwargs)
+    end
+
+    def backoff(attempt)
+      base = 0.5
+      cap  = 8.0
+      exp  = [cap, base * (2**attempt)].min
+      rand * exp
+    end
+  end
+
+  # Resource: /address/*
+  class AddressResource
+    def initialize(client) = (@client = client)
+
+    def search(q, max_results: nil)
+      Models::AddressSearchEnvelope.from_hash(
+        @client.request("/address/search", query: { "q" => q, "max_results" => max_results })
+      )
+    end
+
+    def postcode(postcode, max_results: nil)
+      Models::AddressPostcodeEnvelope.from_hash(
+        @client.request("/address/postcode/#{URI.encode_www_form_component(postcode)}",
+                        query: { "max_results" => max_results })
+      )
+    end
+
+    def udprn(udprn)
+      Models::AddressUdprnEnvelope.from_hash(
+        @client.request("/address/udprn/#{URI.encode_www_form_component(udprn.to_s)}")
+      )
+    end
+  end
+
+  # Resource: /email/*
+  class EmailResource
+    def initialize(client) = (@client = client)
+
+    def validate(address)
+      Models::EmailEnvelope.from_hash(
+        @client.request("/email/#{URI.encode_www_form_component(address)}")
+      )
+    end
+  end
+
+  # Resource: /phone/*
+  class PhoneResource
+    def initialize(client) = (@client = client)
+
+    def validate(number)
+      Models::PhoneEnvelope.from_hash(
+        @client.request("/phone/#{URI.encode_www_form_component(number)}")
+      )
+    end
+  end
+end

data/lib/postio/errors.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Postio
+  # Base class for every Postio API failure.
+  #
+  # All instances carry: status (HTTP code, 0 for transport errors),
+  # error_code (the API's error string), details, request_id, and the
+  # raw envelope hash for any field this class doesn't expose.
+  class Error < StandardError
+    attr_reader :status, :error_code, :details, :request_id, :envelope, :cause_error
+
+    def initialize(message, status: 0, error_code: nil, details: nil, request_id: nil, envelope: nil, cause: nil)
+      super(message)
+      @status      = status
+      @error_code  = error_code
+      @details     = details
+      @request_id  = request_id
+      @envelope    = envelope
+      @cause_error = cause
+    end
+  end
+
+  class ValidationError   < Error; end  # 400 / 422
+  class InvalidKeyError   < Error; end  # 401
+  class OutOfCreditError  < Error; end  # 402
+  class ForbiddenError    < Error; end  # 403
+  class NotFoundError     < Error; end  # 404
+  class ServerError       < Error; end  # 5xx
+  class TimeoutError      < Error; end  # local request timeout
+  class ConnectionError   < Error; end  # transport-level error
+
+  # 429 — rate limited. {#retry_after} is the API's suggested wait in seconds.
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+
+  # Map an HTTP status to the typed error class.
+  STATUS_ERRORS = {
+    400 => ValidationError,
+    401 => InvalidKeyError,
+    402 => OutOfCreditError,
+    403 => ForbiddenError,
+    404 => NotFoundError,
+    422 => ValidationError,
+    429 => RateLimitError
+  }.freeze
+
+  def self.error_class_for(status)
+    return STATUS_ERRORS[status] if STATUS_ERRORS.key?(status)
+    return ServerError if status >= 500
+
+    Error
+  end
+end

data/lib/postio/models.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Postio
+  module Models
+    # Performance — per-request timing breakdown.
+    Performance = Data.define(:worker_ms, :lookup_ms) do
+      def self.from_hash(h)
+        new(worker_ms: h["workerMs"].to_i, lookup_ms: h["lookupMs"].to_i)
+      end
+    end
+
+    # Meta — response envelope metadata for every endpoint except /connect.
+    Meta = Data.define(:count_results, :request_id, :performance) do
+      def self.from_hash(h)
+        new(
+          count_results: h["countResults"].to_i,
+          request_id:    h["requestId"].to_s,
+          performance:   Performance.from_hash(h["performance"])
+        )
+      end
+    end
+
+    # MetaConnect — meta block for /connect (no count).
+    MetaConnect = Data.define(:request_id, :performance) do
+      def self.from_hash(h)
+        new(
+          request_id:  h["requestId"].to_s,
+          performance: Performance.from_hash(h["performance"])
+        )
+      end
+    end
+
+    # AddressSearchResult — a single typeahead hit.
+    AddressSearchResult = Data.define(:udprn, :suggestion) do
+      def self.from_hash(h)
+        new(udprn: h["udprn"].to_i, suggestion: h["suggestion"].to_s)
+      end
+    end
+
+    # Address — full PAF + OS record. Many fields are optional.
+    Address = Data.define(
+      :udprn, :postcode, :postcode_outward, :postcode_inward, :postcode_type,
+      :address_line_1, :address_line_2, :address_line_3, :post_town,
+      :organisation_name, :department_name, :building_name, :building_number,
+      :sub_building_name, :po_box, :thoroughfare, :dependent_thoroughfare,
+      :dependent_locality, :double_dependent_locality, :delivery_point_suffix,
+      :country, :county, :district, :ward,
+      :latitude, :longitude, :eastings, :northings
+    ) do
+      def self.from_hash(h)
+        new(
+          udprn:                       h["udprn"].to_i,
+          postcode:                    h["postcode"].to_s,
+          postcode_outward:            h["postcode_outward"],
+          postcode_inward:             h["postcode_inward"],
+          postcode_type:               h["postcode_type"],
+          address_line_1:              h["address_line_1"],
+          address_line_2:              h["address_line_2"],
+          address_line_3:              h["address_line_3"],
+          post_town:                   h["post_town"],
+          organisation_name:           h["organisation_name"],
+          department_name:             h["department_name"],
+          building_name:               h["building_name"],
+          building_number:             h["building_number"],
+          sub_building_name:           h["sub_building_name"],
+          po_box:                      h["po_box"],
+          thoroughfare:                h["thoroughfare"],
+          dependent_thoroughfare:      h["dependent_thoroughfare"],
+          dependent_locality:          h["dependent_locality"],
+          double_dependent_locality:   h["double_dependent_locality"],
+          delivery_point_suffix:       h["delivery_point_suffix"],
+          country:                     h["country"],
+          county:                      h["county"],
+          district:                    h["district"],
+          ward:                        h["ward"],
+          latitude:                    h["latitude"]&.to_f,
+          longitude:                   h["longitude"]&.to_f,
+          eastings:                    h["eastings"]&.to_i,
+          northings:                   h["northings"]&.to_i
+        )
+      end
+    end
+
+    # EmailResult — validation verdict for one email address.
+    EmailResult = Data.define(
+      :email, :is_valid_syntax, :did_you_mean, :is_disposable, :is_free_provider,
+      :is_role_account, :mx_found, :smtp_check, :is_catch_all, :deliverability
+    ) do
+      DELIVERABILITY_DELIVERABLE   = "deliverable"
+      DELIVERABILITY_UNDELIVERABLE = "undeliverable"
+      DELIVERABILITY_RISKY         = "risky"
+      DELIVERABILITY_UNKNOWN       = "unknown"
+      DELIVERABILITY_INVALID       = "invalid"
+
+      def self.from_hash(h)
+        new(
+          email:            h["email"].to_s,
+          is_valid_syntax:  h["isValidSyntax"] == true,
+          did_you_mean:     h["didYouMean"],
+          is_disposable:    h["isDisposable"] == true,
+          is_free_provider: h["isFreeProvider"] == true,
+          is_role_account:  h["isRoleAccount"] == true,
+          mx_found:         h["mxFound"] == true,
+          smtp_check:       h["smtpCheck"],
+          is_catch_all:     h["isCatchAll"],
+          deliverability:   h["deliverability"].to_s
+        )
+      end
+    end
+
+    # PhoneResult — validation verdict for one phone number.
+    #
+    # SPEC DRIFT (2026-05-02): the OpenAPI spec marks every nullable
+    # field as required, but on invalid input the live API drops them
+    # entirely. The .from_hash fetcher uses h["..."] which returns nil
+    # for missing keys, papering over the drift. Also: spec says
+    # is_reachable is string|null, but the live API returns bool — we
+    # accept either.
+    PhoneResult = Data.define(
+      :number, :is_valid, :is_possible, :type, :country_code, :country_name,
+      :national_format, :international_format, :e164_format, :original_carrier,
+      :current_carrier, :is_ported, :is_reachable, :mcc, :mnc, :level, :lookup_error
+    ) do
+      def self.from_hash(h)
+        new(
+          number:               h["number"].to_s,
+          is_valid:             h["isValid"] == true,
+          is_possible:          h["isPossible"] == true,
+          type:                 h["type"],
+          country_code:         h["countryCode"],
+          country_name:         h["countryName"],
+          national_format:      h["nationalFormat"],
+          international_format: h["internationalFormat"],
+          e164_format:          h["e164Format"],
+          original_carrier:     h["originalCarrier"],
+          current_carrier:      h["currentCarrier"],
+          is_ported:            h["isPorted"],
+          is_reachable:         h["isReachable"],
+          mcc:                  h["mcc"],
+          mnc:                  h["mnc"],
+          level:                h["level"],
+          lookup_error:         h["lookupError"]
+        )
+      end
+    end
+
+    # Envelopes — one per endpoint.
+    AddressSearchEnvelope = Data.define(:success, :results, :meta) do
+      def self.from_hash(h)
+        new(
+          success: h["success"] == true,
+          results: (h["results"] || []).map { |r| AddressSearchResult.from_hash(r) },
+          meta:    Meta.from_hash(h["meta"])
+        )
+      end
+    end
+
+    AddressPostcodeEnvelope = Data.define(:success, :results, :meta) do
+      def self.from_hash(h)
+        new(
+          success: h["success"] == true,
+          results: (h["results"] || []).map { |r| Address.from_hash(r) },
+          meta:    Meta.from_hash(h["meta"])
+        )
+      end
+    end
+
+    AddressUdprnEnvelope = Data.define(:success, :results, :meta) do
+      def self.from_hash(h)
+        new(
+          success: h["success"] == true,
+          results: (h["results"] || []).map { |r| Address.from_hash(r) },
+          meta:    Meta.from_hash(h["meta"])
+        )
+      end
+    end
+
+    EmailEnvelope = Data.define(:success, :results, :meta) do
+      def self.from_hash(h)
+        new(
+          success: h["success"] == true,
+          results: (h["results"] || []).map { |r| EmailResult.from_hash(r) },
+          meta:    Meta.from_hash(h["meta"])
+        )
+      end
+    end
+
+    PhoneEnvelope = Data.define(:success, :results, :meta) do
+      def self.from_hash(h)
+        new(
+          success: h["success"] == true,
+          results: (h["results"] || []).map { |r| PhoneResult.from_hash(r) },
+          meta:    Meta.from_hash(h["meta"])
+        )
+      end
+    end
+
+    ConnectSuccess = Data.define(:success, :meta) do
+      def self.from_hash(h)
+        new(success: h["success"] == true, meta: MetaConnect.from_hash(h["meta"]))
+      end
+    end
+  end
+end

data/lib/postio/version.rb

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

data/lib/postio.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "postio/version"
+require_relative "postio/errors"
+require_relative "postio/models"
+require_relative "postio/client"
+
+# Top-level Postio module. Use Postio::Client to construct the API client.
+#
+#   client = Postio::Client.new(api_key: "pk_live_...")
+#   client.address.search("downing street")
+module Postio
+end

data/postio.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/postio/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "postio"
+  spec.version     = Postio::VERSION
+  spec.authors     = ["Postio"]
+  spec.email       = ["admin@postio.co.uk"]
+
+  spec.summary     = "Ruby SDK for the Postio API — UK address, email, and phone validation."
+  spec.description = "Ruby client for the Postio API. UK address, email, and phone validation backed by Royal Mail PAF and Ordnance Survey. Stdlib net/http, no external runtime dependencies."
+  spec.homepage    = "https://postio.co.uk"
+  spec.license     = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata = {
+    "homepage_uri"      => "https://postio.co.uk",
+    "documentation_uri" => "https://postio.co.uk/docs",
+    "source_code_uri"   => "https://github.com/postio-uk/postio-ruby",
+    "bug_tracker_uri"   => "https://github.com/postio-uk/postio-ruby/issues",
+    "changelog_uri"     => "https://github.com/postio-uk/postio-ruby/blob/master/CHANGELOG.md",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir["lib/**/*.rb", "README.md", "LICENSE", "CHANGELOG.md", "postio.gemspec"]
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "webmock", "~> 3.23"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.65"
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: postio
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Postio
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+description: Ruby client for the Postio API. UK address, email, and phone validation
+  backed by Royal Mail PAF and Ordnance Survey. Stdlib net/http, no external runtime
+  dependencies.
+email:
+- admin@postio.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/postio.rb
+- lib/postio/client.rb
+- lib/postio/errors.rb
+- lib/postio/models.rb
+- lib/postio/version.rb
+- postio.gemspec
+homepage: https://postio.co.uk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://postio.co.uk
+  documentation_uri: https://postio.co.uk/docs
+  source_code_uri: https://github.com/postio-uk/postio-ruby
+  bug_tracker_uri: https://github.com/postio-uk/postio-ruby/issues
+  changelog_uri: https://github.com/postio-uk/postio-ruby/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby SDK for the Postio API — UK address, email, and phone validation.
+test_files: []