postal_codes_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: afd74ae3b8c6bcd3daf44f1b77ef6744fcfde28c52ca1ce29ee51dd2bba8b017
+  data.tar.gz: 341b3d9bd9731b211dd1e303ced461d9a1e4cd0a41508f657b54cf75e2825d1e
+SHA512:
+  metadata.gz: 97b7403b75759f1e96cfb50294cb3037e1469c04b50b5f5008811440d16b6624a1bb36a3695a1ad32c121cb1b997f879a08dddcd128bcb73bf6b24709ef3c771
+  data.tar.gz: cd34f45d135c586061e238412017d55aa7045ddfc708ff56a5493c9e72aff84cc8db1ec895a9caac96e164cbf03970fc1e3b9b6a8ac813e0cb8265d33d000018

data/README.md

@@ -0,0 +1,83 @@
+# PostalCodesClient
+
+Ruby-Client-Gem für die PLZ API – Postleitzahlen-Suche über 100+ Länder.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "postal_codes_client", path: "../postal_codes_client"
+```
+
+Oder als lokales Gem:
+
+```bash
+cd postal_codes_client
+gem build postal_codes_client.gemspec
+gem install postal_codes_client-0.1.0.gem
+```
+
+## Konfiguration
+
+```ruby
+require "postal_codes_client"
+
+PostalCodesClient.configure do |config|
+  config.base_url  = "http://localhost:3000"  # Standard
+  config.api_token = "dein_api_token"
+  config.timeout   = 30                       # Sekunden (Standard)
+end
+```
+
+## Verwendung
+
+### Client erstellen
+
+```ruby
+# Globale Konfiguration nutzen
+client = PostalCodesClient::Client.new
+
+# Oder Token direkt übergeben
+client = PostalCodesClient::Client.new(
+  api_token: "dein_api_token",
+  base_url: "https://api.example.com"
+)
+```
+
+```ruby
+# PLZ-Suche (Teilsuche möglich)
+results = client.postal_codes.search(q: "803", country: "DE")
+results[:results].each do |pc|
+  puts "#{pc[:zipcode]} #{pc[:place]} (#{pc[:state]})"
+end
+
+# Suche ohne Länderfilter
+results = client.postal_codes.search(q: "1010", limit: 10)
+
+# Verfügbare Länder auflisten
+countries = client.postal_codes.countries
+puts countries[:countries].join(", ")
+```
+
+### Fehlerbehandlung
+
+```ruby
+begin
+  client.postal_codes.search(q: "803")
+rescue PostalCodesClient::AuthenticationError => e
+  puts "Nicht autorisiert: #{e.message}"
+rescue PostalCodesClient::ValidationError => e
+  puts "Validierungsfehler: #{e.errors.join(', ')}"
+rescue PostalCodesClient::ApiError => e
+  puts "API-Fehler (#{e.status}): #{e.message}"
+rescue PostalCodesClient::Error => e
+  puts "Fehler: #{e.message}"
+end
+```
+
+## API-Referenz
+
+| Methode | Beschreibung |
+|---------|-------------|
+| `client.postal_codes.search(q:, country:, limit:)` | PLZ-Suche |
+| `client.postal_codes.countries` | Verfügbare Länder |

data/lib/postal_codes_client/client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module PostalCodesClient
+  class Client
+    attr_reader :auth, :postal_codes
+
+    def initialize(api_token: nil, base_url: nil)
+      @api_token = api_token || PostalCodesClient.configuration.api_token
+      @base_url  = base_url  || PostalCodesClient.configuration.base_url
+      @timeout   = PostalCodesClient.configuration.timeout
+
+      @auth         = Resources::Auth.new(self)
+      @postal_codes = Resources::PostalCodes.new(self)
+    end
+
+    # Update the API token (e.g. after login or token regeneration).
+    def api_token=(token)
+      @api_token = token
+    end
+
+    # Perform a GET request.
+    def get(path, params = {})
+      uri = build_uri(path, params)
+      request = Net::HTTP::Get.new(uri)
+      execute(uri, request)
+    end
+
+    # Perform a POST request with a JSON body.
+    def post(path, body = nil)
+      uri = build_uri(path)
+      request = Net::HTTP::Post.new(uri)
+      if body
+        request.body = JSON.generate(body)
+        request["Content-Type"] = "application/json"
+      end
+      execute(uri, request)
+    end
+
+    private
+
+    def build_uri(path, params = {})
+      uri = URI.join(@base_url, path)
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      uri
+    end
+
+    def execute(uri, request)
+      request["Authorization"] = "Bearer #{@api_token}" if @api_token
+      request["Accept"] = "application/json"
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      body = response.body ? JSON.parse(response.body, symbolize_names: true) : nil
+
+      case response.code.to_i
+      when 200, 201
+        body
+      when 401
+        raise AuthenticationError, body&.dig(:error) || "Unauthorized"
+      when 422
+        raise ValidationError.new(
+          body&.dig(:error) || "Validation failed",
+          errors: body&.dig(:errors) || []
+        )
+      else
+        raise ApiError.new(
+          body&.dig(:error) || "API error (HTTP #{response.code})",
+          status: response.code.to_i,
+          body: body
+        )
+      end
+    end
+  end
+end

data/lib/postal_codes_client/configuration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PostalCodesClient
+  class Configuration
+    attr_accessor :base_url, :api_token, :timeout
+
+    def initialize
+      @base_url = "http://localhost:3000"
+      @api_token = nil
+      @timeout = 30
+    end
+  end
+end

data/lib/postal_codes_client/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PostalCodesClient
+  class Error < StandardError; end
+
+  class AuthenticationError < Error; end
+
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(message, errors: [])
+      @errors = errors
+      super(message)
+    end
+  end
+
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status:, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+  end
+end

data/lib/postal_codes_client/resources/postal_codes.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PostalCodesClient
+  module Resources
+    class PostalCodes
+      def initialize(client)
+        @client = client
+      end
+
+      # Search for postal codes.
+      #
+      # @param q [String] Full or partial postal code (required)
+      # @param country [String, nil] ISO country code, e.g. "DE", "AT", "CH"
+      # @param limit [Integer, nil] Max results (default 50, max 200)
+      # @return [Hash] { query:, country:, count:, results: [...] }
+      def search(q:, country: nil, limit: nil)
+        params = { q: q }
+        params[:country] = country if country
+        params[:limit] = limit if limit
+        @client.get("/api/v1/postal_codes", params)
+      end
+
+      # List all available country codes.
+      #
+      # @return [Hash] { countries: ["AT", "CH", "DE", ...] }
+      def countries
+        @client.get("/api/v1/postal_codes/countries")
+      end
+    end
+  end
+end

data/lib/postal_codes_client/version.rb

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

data/lib/postal_codes_client.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "postal_codes_client/version"
+require_relative "postal_codes_client/configuration"
+require_relative "postal_codes_client/errors"
+require_relative "postal_codes_client/resources/auth"
+require_relative "postal_codes_client/resources/postal_codes"
+require_relative "postal_codes_client/client"
+
+module PostalCodesClient
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: postal_codes_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- PLZ API
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Ruby gem to search postal codes across 100+ countries via the PLZ API.
+  Supports authentication, postal code search, and country listing.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/postal_codes_client.rb
+- lib/postal_codes_client/client.rb
+- lib/postal_codes_client/configuration.rb
+- lib/postal_codes_client/errors.rb
+- lib/postal_codes_client/resources/postal_codes.rb
+- lib/postal_codes_client/version.rb
+homepage: https://github.com/postal-codes-rails
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Ruby client for the PLZ (Postleitzahlen) API
+test_files: []