staddress 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b5619831aa074839a1fdb4b2c4db74dd302d3c22effb66dec18416fb676064b6
+  data.tar.gz: c9f03cf74fbaef729e88fddfb9fc1c65f00da9af004c7865b2863ca3175a7793
+SHA512:
+  metadata.gz: 45d4ac6515b8b6f1da89d9d6dcfbfa8d3b862a228e4031dea9100566bdef54cdbc600d8fe8ca299405608ea8fc115e7c91ca8e15bd64070c1f6d9aa00929e2b6
+  data.tar.gz: 5c4fe314c6eb3342ea07766c8ccab57b853f4480aeb8f1750b1b77d14a4272928d73435956b9c8ee99e6fe84dec870ee11b88c60b139b0e43e3c7cac57d8aacd

data/README.md

@@ -0,0 +1,85 @@
+# staddress (Ruby Gem)
+
+Staddress AI API 公式 Ruby SDK。
+
+## ステータス
+
+**Phase 4 — v0.1 実装済み**（`parse_address` / `parse_batch` / `get_usage`）
+
+- HTTP: 標準ライブラリ `net/http`（**ランタイム依存なし**）
+- Ruby 3.1+
+
+## インストール
+
+```bash
+gem install staddress
+```
+
+```ruby
+# Gemfile
+gem "staddress"
+```
+
+## 使い方
+
+```ruby
+require "staddress"
+
+client = Staddress::Client.new(
+  api_key: "sk_xxx",                      # 省略時は環境変数 STADDRESS_API_KEY
+  base_url: "https://api.staddress.com",  # 省略時は既定値（STADDRESS_BASE_URL も可）
+  timeout: 30                             # 任意（秒）
+)
+
+# 単件解析
+result = client.parse_address(input: "六本木ヒルズ 森タワー 52F", postal_code: "106-6100")
+puts result.normalized
+puts result.components.pref
+
+# 一括解析（Standard プラン以上、最大 100 件）
+results = client.parse_batch([
+  { id: "1", address: "東京都渋谷区道玄坂1-2-3" },
+  { id: "2", address: "大阪府大阪市北区梅田1-1-1" }
+])
+results.each { |item| puts "#{item.id}: #{item.result&.normalized}" }
+
+# 利用状況
+usage = client.get_usage
+puts "#{usage.plan} / #{usage.account_name}"
+```
+
+## エラーハンドリング
+
+API エラー・ネットワークエラーは `Staddress::Error` として送出されます。
+
+```ruby
+begin
+  client.parse_address(input: "...")
+rescue Staddress::Error => err
+  err.code         # 例: "unauthorized", "quota_exceeded", "unresolved"
+  err.http_status  # HTTP ステータス（ネットワークエラー時は 0）
+  err.request_id   # サポート問い合わせ用（あれば）
+  err.retry_after  # 再試行可能日時（あれば）
+end
+```
+
+## API
+
+| メソッド | HTTP | 説明 |
+| --- | --- | --- |
+| `parse_address(input:, postal_code: nil)` | `POST /api/v1/addresses/parse` | 単件解析 → `Models::ParseResult` |
+| `parse_batch(items)` | `POST /api/v1/addresses/parse/batch` | 一括解析 → `Array<Models::BatchItemResult>` |
+| `get_usage` | `GET /api/v1/usage` | 利用状況 → `Models::UsageResponse` |
+
+レスポンスモデルは snake_case アクセサ（`match_level` 等）でアクセスでき、未知フィールドは `#raw`（元の Hash）から参照できます。
+
+## 開発
+
+```bash
+cd packages/ruby
+bundle install
+bundle exec rspec     # 単体テスト（webmock でモック、実 API 不要）
+gem build staddress.gemspec
+```
+
+詳細: [docs/plan-tools.md §3.6](../../docs/plan-tools.md)

data/lib/staddress/client.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+require_relative "errors"
+require_relative "models"
+
+module Staddress
+  DEFAULT_BASE_URL = "https://api.staddress.com"
+  DEFAULT_TIMEOUT = 30
+  MAX_BATCH_ITEMS = 100
+
+  # Staddress AI API クライアント（同期）。
+  #
+  # 例:
+  #   client = Staddress::Client.new(api_key: "sk_xxx")
+  #   result = client.parse_address(input: "六本木ヒルズ 森タワー 52F")
+  #   puts result.normalized
+  class Client
+    # @param api_key [String, nil] 省略時は環境変数 STADDRESS_API_KEY
+    # @param base_url [String, nil] 省略時は STADDRESS_BASE_URL または既定値
+    # @param timeout [Numeric] 接続・読み取りタイムアウト（秒）
+    def initialize(api_key: nil, base_url: nil, timeout: DEFAULT_TIMEOUT)
+      @api_key = api_key || ENV.fetch("STADDRESS_API_KEY", nil)
+      if @api_key.nil? || @api_key.empty?
+        raise Error.new(
+          "API キーが設定されていません。api_key 引数または環境変数 STADDRESS_API_KEY を指定してください。",
+          code: "unauthorized",
+          http_status: 0
+        )
+      end
+
+      base = base_url || ENV.fetch("STADDRESS_BASE_URL", nil) || DEFAULT_BASE_URL
+      @base_url = base.sub(%r{/+\z}, "")
+      @timeout = timeout
+    end
+
+    # 単件住所解析 (POST /api/v1/addresses/parse)。
+    # @return [Staddress::Models::ParseResult]
+    def parse_address(input:, postal_code: nil)
+      if input.nil? || input.empty?
+        raise Error.new("input は必須です。", code: "invalid_request", http_status: 0)
+      end
+
+      body = { "input" => input }
+      body["postalCode"] = postal_code if postal_code && !postal_code.empty?
+
+      data = request("POST", "/api/v1/addresses/parse", body)
+      Models::ParseResult.from(data["result"]) || Models::ParseResult.from({})
+    end
+
+    # 一括住所解析 (POST /api/v1/addresses/parse/batch)。Standard プラン以上、最大 100 件。
+    # @param items [Array<Hash>] 例: [{ id: "1", address: "東京都..." }]
+    # @return [Array<Staddress::Models::BatchItemResult>]
+    def parse_batch(items)
+      list = items.to_a
+      if list.empty?
+        raise Error.new("items には1件以上を指定してください。", code: "invalid_request", http_status: 0)
+      end
+      if list.size > MAX_BATCH_ITEMS
+        raise Error.new(
+          "items は最大 #{MAX_BATCH_ITEMS} 件です（現在: #{list.size} 件）。",
+          code: "batch_size_exceeded",
+          http_status: 0
+        )
+      end
+
+      data = request("POST", "/api/v1/addresses/parse/batch", { "items" => list })
+      (data["results"] || []).map { |item| Models::BatchItemResult.from(item) }
+    end
+
+    # 利用状況取得 (GET /api/v1/usage)。
+    # @return [Staddress::Models::UsageResponse]
+    def get_usage
+      data = request("GET", "/api/v1/usage", nil)
+      Models::UsageResponse.from(data)
+    end
+
+    private
+
+    def request(method, path, body)
+      uri = URI.parse("#{@base_url}#{path}")
+      req = build_request(method, uri, body)
+      req["X-Api-Key"] = @api_key
+      req["Content-Type"] = "application/json"
+
+      response = perform(uri, req)
+      interpret(response.code.to_i, response.body)
+    end
+
+    def build_request(method, uri, body)
+      klass = { "GET" => Net::HTTP::Get, "POST" => Net::HTTP::Post }.fetch(method)
+      req = klass.new(uri)
+      req.body = JSON.generate(body) unless body.nil?
+      req
+    end
+
+    def perform(uri, req)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.request(req)
+    rescue Net::OpenTimeout, Net::ReadTimeout
+      raise Error.new("リクエストがタイムアウトしました。", code: "timeout", http_status: 0)
+    rescue SocketError, SystemCallError, IOError
+      raise Error.new("ネットワークエラーが発生しました。", code: "network_error", http_status: 0)
+    end
+
+    # HTTP レスポンスを解釈し、成功なら Hash を返す。エラーなら Error を送出する。
+    def interpret(status, text)
+      data = parse_json(text, status)
+
+      if status >= 400
+        err = data.is_a?(Hash) ? data["error"] : nil
+        if err.is_a?(Hash) && err["code"] && err["message"]
+          raise Error.from_body(err, status)
+        end
+
+        raise Error.new("API エラー (HTTP #{status})", code: "internal_error", http_status: status)
+      end
+
+      data.is_a?(Hash) ? data : {}
+    end
+
+    def parse_json(text, status)
+      return nil if text.nil? || text.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError
+      raise Error.new("レスポンスの JSON 解析に失敗しました。", code: "internal_error", http_status: status)
+    end
+  end
+end

data/lib/staddress/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Staddress
+  # Staddress API 呼び出しで発生したエラーを表す統一例外。
+  #
+  # - HTTP 4xx / 5xx で API がエラーボディを返した場合
+  # - ネットワークエラー・タイムアウト（code: "network_error" / "timeout"）
+  # - 入力バリデーションエラー（code: "invalid_request"）
+  #
+  # 属性:
+  #   code         API エラーコード（"unauthorized", "quota_exceeded" 等）
+  #   http_status  HTTP ステータスコード（ネットワークエラー時は 0）
+  #   request_id   サポート問い合わせ用のリクエスト ID（あれば）
+  #   retry_after  再試行可能日時（ISO 8601、あれば）
+  class Error < StandardError
+    attr_reader :code, :http_status, :request_id, :retry_after
+
+    def initialize(message, code: "internal_error", http_status: 0, request_id: nil, retry_after: nil)
+      super(message)
+      @code = code
+      @http_status = http_status
+      @request_id = request_id
+      @retry_after = retry_after
+    end
+
+    # API のエラーボディ（Hash）から Error を生成する。
+    def self.from_body(body, http_status)
+      new(
+        body["message"] || "API error (#{body["code"]})",
+        code: body["code"],
+        http_status: http_status,
+        request_id: body["requestId"],
+        retry_after: body["retryAfter"]
+      )
+    end
+  end
+end

data/lib/staddress/models.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Staddress
+  # Staddress AI API のデータモデル。
+  #
+  # OpenAPI 定義（openapi/staddress-api.yaml）に準拠する。
+  # API は camelCase、Ruby 側は snake_case アクセサでアクセスできるようマッピングする。
+  # 未知のフィールドは +raw+（元の Hash）から参照できる（前方互換）。
+  module Models
+    class Base
+      # 元の（パース済み）レスポンス Hash。未定義フィールドはここから参照できる。
+      attr_reader :raw
+
+      class << self
+        def fields
+          @fields ||= {}
+        end
+
+        # フィールド定義。
+        #   name  Ruby 側の snake_case 名（アクセサになる）
+        #   key:  JSON 側のキー（省略時は name を camelCase 化）
+        #   model: ネストしたモデルクラス
+        #   list: true なら配列としてマッピング
+        def field(name, key: nil, model: nil, list: false)
+          fields[name] = { key: key || camelize(name), model: model, list: list }
+          attr_reader name
+        end
+
+        # Hash からインスタンスを生成する。nil の場合は nil を返す。
+        def from(data)
+          return nil if data.nil?
+
+          obj = allocate
+          obj.send(:populate, data, fields)
+          obj
+        end
+
+        def camelize(name)
+          head, *rest = name.to_s.split("_")
+          (rest.empty? ? head : head + rest.map(&:capitalize).join)
+        end
+      end
+
+      private
+
+      def populate(data, fields)
+        @raw = data
+        fields.each do |name, meta|
+          value = data[meta[:key]]
+          value = data[meta[:key].to_sym] if value.nil?
+          instance_variable_set("@#{name}", cast(value, meta))
+        end
+      end
+
+      def cast(value, meta)
+        return nil if value.nil?
+        return value unless meta[:model]
+        return value.map { |item| meta[:model].from(item) } if meta[:list]
+
+        meta[:model].from(value)
+      end
+    end
+
+    # 住所の構成要素。
+    class AddressComponents < Base
+      field :pref
+      field :pref_code
+      field :city
+      field :city_code
+      field :oaza_cho
+      field :chome_koaza
+      field :chome_koaza_normalized
+      field :chome_number
+      field :street_number_block
+      field :building_name
+      field :room_number
+      field :room_number_unit
+      field :lon
+      field :lat
+      field :lg_code
+      field :machiaza_id
+    end
+
+    # 解析の信頼度。
+    class Confidence < Base
+      field :score
+      field :match_level
+      field :query
+    end
+
+    # 住所解析結果。
+    class ParseResult < Base
+      field :normalized
+      field :standard
+      field :components, model: AddressComponents
+      field :confidence, model: Confidence
+    end
+
+    # API エラー本体（エラーレスポンスの error フィールド）。
+    class ErrorBody < Base
+      field :code
+      field :message
+      field :request_id
+      field :retry_after
+    end
+
+    # 一括解析の結果アイテム（result か error のいずれかを持つ）。
+    class BatchItemResult < Base
+      field :id
+      field :result, model: ParseResult
+      field :error, model: ErrorBody
+    end
+
+    class UsagePeriod < Base
+      field :start
+      field :end
+    end
+
+    class UsageCredit < Base
+      field :valid_until
+      field :total_amount
+      field :used_amount
+      field :remaining
+    end
+
+    class UsageDetail < Base
+      field :period, model: UsagePeriod
+      field :count
+      field :monthly_limit
+      field :contract_period_remaining
+      field :credits, model: UsageCredit, list: true
+    end
+
+    # 利用状況レスポンス。
+    class UsageResponse < Base
+      field :account_name
+      field :plan
+      field :usage, model: UsageDetail
+    end
+  end
+end

data/lib/staddress/version.rb

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

data/lib/staddress.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "staddress/version"
+require_relative "staddress/errors"
+require_relative "staddress/models"
+require_relative "staddress/client"
+
+# Staddress AI API 公式 Ruby SDK。
+module Staddress
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: staddress
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- StaddressAI
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-15 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'
+description: Ruby SDK for the Staddress AI address parsing API (parse_address / parse_batch
+  / get_usage). Zero runtime dependencies.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/staddress.rb
+- lib/staddress/client.rb
+- lib/staddress/errors.rb
+- lib/staddress/models.rb
+- lib/staddress/version.rb
+homepage: https://staddress.com/api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://staddress.com/api
+  source_code_uri: https://github.com/StaddressAI/staddress-tools
+  bug_tracker_uri: https://github.com/StaddressAI/staddress-tools/issues
+  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.1'
+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: Official Ruby client for Staddress AI address parsing API
+test_files: []