pickpoint 2.0.3

data/lib/pickpoint/config.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Pickpoint
+  DEFAULT_BASE_URL = "https://api.pickpoint.io"
+  DEFAULT_MAX_RETRIES = 3
+  DEFAULT_RETRY_BASE = 1.0 # seconds
+  MIN_RETRY_BASE = 0.2
+  DEFAULT_TIMEOUT = 30.0
+  MAX_CONCURRENCY = 20
+  DEFAULT_CONCURRENCY = 20
+  CLIENT_AUTH_REFRESH_AT = 0.5
+
+  # Pair from POST /v2/client-tokens. +expires_at+ is unix epoch milliseconds.
+  ClientAuth = Struct.new(:access_token, :refresh_token, :expires_at, keyword_init: true)
+
+  # Public-api client config. Provide exactly one of +api_key+ / +client_auth+ / +access_token+.
+  class Config
+    attr_accessor :api_key, :client_auth, :access_token, :base_url,
+                  :max_retries, :retry_base, :timeout, :concurrency, :http_adapter
+
+    def initialize(
+      api_key: nil,
+      client_auth: nil,
+      access_token: nil,
+      base_url: nil,
+      max_retries: nil,
+      retry_base: nil,
+      timeout: nil,
+      concurrency: nil,
+      http_adapter: nil
+    )
+      @api_key = api_key
+      @client_auth = client_auth
+      @access_token = access_token
+      @base_url = base_url
+      @max_retries = max_retries
+      @retry_base = retry_base
+      @timeout = timeout
+      @concurrency = concurrency
+      # Optional callable: call(method, url, headers, body) -> [status, body]
+      @http_adapter = http_adapter
+    end
+  end
+end

data/lib/pickpoint/devices.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Pickpoint
+  Device = Struct.new(
+    :uid, :id, :name, :status, :description, :tracks_count, :type, :secret,
+    :metadata, :created_at, :updated_at, :last_location,
+    keyword_init: true
+  ) do
+    def self.from_hash(d)
+      d = d.transform_keys(&:to_s)
+      new(
+        id: (d["id"] || 0).to_i,
+        uid: (d["uid"] || "").to_s,
+        name: (d["name"] || "").to_s,
+        status: (d["status"] || "").to_s,
+        description: d["description"],
+        tracks_count: (d["tracksCount"] || 0).to_i,
+        type: (d["type"] || "").to_s,
+        secret: (d["secret"] || "").to_s,
+        metadata: d["metadata"],
+        created_at: (d["createdAt"] || "").to_s,
+        updated_at: (d["updatedAt"] || "").to_s,
+        last_location: d["lastLocation"]
+      )
+    end
+  end
+
+  DeviceInput = Struct.new(:name, :type, :description, :metadata, keyword_init: true) do
+    def to_h
+      out = { "name" => name, "type" => type }
+      out["description"] = description unless description.nil?
+      out["metadata"] = metadata unless metadata.nil?
+      out
+    end
+  end
+
+  DeviceListResult = Struct.new(:data, :total, keyword_init: true)
+  DeviceListQuery = Struct.new(:skip, :take, :search, :idle, keyword_init: true)
+  DeviceCommandResult = Struct.new(:delivered, keyword_init: true)
+
+  class DevicesService
+    def initialize(transport)
+      @t = transport
+    end
+
+    def list(query = nil)
+      q = query || DeviceListQuery.new
+      params = {}
+      params["skip"] = q.skip.to_s if q.skip && q.skip.to_i.positive?
+      params["take"] = q.take.to_s if q.take && q.take.to_i.positive?
+      params["search"] = q.search if q.search && !q.search.empty?
+      params["idle"] = "1" if q.idle
+
+      raw = @t.do(Transport::RequestOpts.new(method: "GET", path: "/v2/devices", query: params))
+      body = JSON.parse(raw)
+      DeviceListResult.new(
+        data: Array(body["data"]).map { |x| Device.from_hash(x) },
+        total: (body["total"] || 0).to_i
+      )
+    end
+
+    def get(uid)
+      path = "/v2/devices/#{URI.encode_www_form_component(uid)}"
+      raw = @t.do(Transport::RequestOpts.new(method: "GET", path: path))
+      Device.from_hash(JSON.parse(raw))
+    end
+
+    def create(input)
+      raw = @t.do(Transport::RequestOpts.new(method: "POST", path: "/v2/devices", body: input.to_h))
+      Device.from_hash(JSON.parse(raw))
+    end
+
+    def update(uid, input)
+      path = "/v2/devices/#{URI.encode_www_form_component(uid)}"
+      raw = @t.do(Transport::RequestOpts.new(method: "PATCH", path: path, body: input.to_h))
+      Device.from_hash(JSON.parse(raw))
+    end
+
+    def delete(uid)
+      path = "/v2/devices/#{URI.encode_www_form_component(uid)}"
+      @t.do(Transport::RequestOpts.new(method: "DELETE", path: path))
+      nil
+    end
+
+    def command(uid, payload)
+      path = "/v2/devices/#{URI.encode_www_form_component(uid)}/command"
+      # pack("m0") = strict Base64 (no newlines); avoids the base64 gem (not default since 3.4)
+      b64 = [payload.to_s.b].pack("m0")
+      raw = @t.do(
+        Transport::RequestOpts.new(
+          method: "POST",
+          path: path,
+          body: { "payload" => b64 }
+        )
+      )
+      body = JSON.parse(raw)
+      DeviceCommandResult.new(delivered: (body["delivered"] || 0).to_i)
+    end
+  end
+end

data/lib/pickpoint/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Pickpoint
+  class Error < StandardError; end
+
+  class AuthError < Error; end
+  class NotFoundError < Error; end
+  class ConflictError < Error; end
+  class InvalidConfigError < Error; end
+
+  # Non-2xx public-api response (or transport failure after retries).
+  class APIError < Error
+    attr_reader :status, :code, :body
+
+    def initialize(status: 0, code: "", message: "", body: "")
+      @status = status
+      @code = code.to_s
+      @body = body.is_a?(String) ? body.b : body.to_s.b
+      msg = message.empty? ? "request failed (status=#{status} code=#{code})" : message
+      super("pickpoint: #{msg} (status=#{status} code=#{code})")
+    end
+
+    def auth?
+      %w[API_AUTH REFRESH_FAILED].include?(code)
+    end
+
+    def not_found?
+      code == "NOT_FOUND"
+    end
+
+    def conflict?
+      code == "CONFLICT"
+    end
+
+    def invalid_config?
+      code == "INVALID_CONFIG"
+    end
+  end
+end

data/lib/pickpoint/geocoding.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "json"
+require "thread"
+
+module Pickpoint
+  class GeocodingService
+    def initialize(transport, concurrency)
+      @t = transport
+      @concurrency = concurrency
+    end
+
+    def forward(query)
+      raw = @t.do(
+        Transport::RequestOpts.new(
+          method: "GET",
+          path: "/v2/geocode/forward",
+          query: stringify_query(query),
+          on_client_error: Transport::ON_EMPTY,
+          empty: "[]"
+        )
+      )
+      decode_json_array(raw)
+    end
+
+    def reverse(query)
+      raw = @t.do(
+        Transport::RequestOpts.new(
+          method: "GET",
+          path: "/v2/geocode/reverse",
+          query: stringify_query(query),
+          on_client_error: Transport::ON_EMPTY,
+          empty: "null"
+        )
+      )
+      return nil if raw.nil? || raw.empty? || raw == "null"
+
+      JSON.parse(raw)
+    end
+
+    def lookup(query)
+      raw = @t.do(
+        Transport::RequestOpts.new(
+          method: "GET",
+          path: "/v2/address/lookup",
+          query: stringify_query(query),
+          on_client_error: Transport::ON_EMPTY,
+          empty: "[]"
+        )
+      )
+      decode_json_array(raw)
+    end
+
+    def forward_batch(queries)
+      run_batch(queries) { |q| forward(q) }
+    end
+
+    def reverse_batch(queries)
+      run_batch(queries) { |q| reverse(q) }
+    end
+
+    def lookup_batch(queries)
+      run_batch(queries) { |q| lookup(q) }
+    end
+
+    private
+
+    def stringify_query(query)
+      (query || {}).transform_keys(&:to_s).transform_values(&:to_s)
+    end
+
+    def decode_json_array(raw)
+      return [] if raw.nil? || raw.empty?
+
+      begin
+        out = JSON.parse(raw)
+      rescue JSON::ParserError => e
+        raise APIError.new(code: "INVALID_JSON", message: e.message, body: raw)
+      end
+      return out if out.is_a?(Array)
+      return [] if out.nil?
+
+      [out]
+    end
+
+    def run_batch(inputs)
+      inputs = Array(inputs)
+      return [] if inputs.empty?
+
+      concurrency = [@concurrency.to_i, 1].max
+      out = Array.new(inputs.length)
+      first_err = nil
+      err_mutex = Mutex.new
+      queue = Queue.new
+      inputs.each_with_index { |q, i| queue << [i, q] }
+
+      workers = [concurrency, inputs.length].min.times.map do
+        Thread.new do
+          loop do
+            break if err_mutex.synchronize { first_err }
+
+            begin
+              i, q = queue.pop(true)
+            rescue ThreadError
+              break
+            end
+
+            begin
+              out[i] = yield(q)
+            rescue StandardError => e
+              err_mutex.synchronize { first_err ||= e }
+            end
+          end
+        end
+      end
+
+      workers.each(&:join)
+      raise first_err if first_err
+
+      out
+    end
+  end
+end

data/lib/pickpoint/http.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Pickpoint
+  # Thin Net::HTTP wrapper. Optional +adapter+ responds to
+  # +call(method, url, headers, body) -> [status, body_string]+.
+  class Http
+    def initialize(timeout:, adapter: nil)
+      @timeout = timeout
+      @adapter = adapter
+    end
+
+    def request(method, url, headers: {}, body: nil)
+      return @adapter.call(method, url, headers, body) if @adapter
+
+      uri = URI(url)
+      req = build_request(method, uri, body)
+      headers.each { |k, v| req[k] = v }
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      res = http.request(req)
+      [res.code.to_i, res.body.to_s]
+    end
+
+    private
+
+    def build_request(method, uri, body)
+      m = method.to_s.upcase
+      klass =
+        case m
+        when "GET" then Net::HTTP::Get
+        when "POST" then Net::HTTP::Post
+        when "PATCH" then Net::HTTP::Patch
+        when "PUT" then Net::HTTP::Put
+        when "DELETE" then Net::HTTP::Delete
+        else
+          raise InvalidConfigError, "unsupported HTTP method: #{m}"
+        end
+
+      req = klass.new(uri.request_uri)
+      unless body.nil?
+        req["Content-Type"] = "application/json"
+        req.body = body
+      end
+      req
+    end
+  end
+end

data/lib/pickpoint/mint.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pickpoint
+  TokenPair = Struct.new(
+    :access_token, :refresh_token, :expires_at, :expires_in, :scopes,
+    keyword_init: true
+  ) do
+    def self.from_hash(d)
+      d = d.transform_keys(&:to_s)
+      new(
+        access_token: (d["accessToken"] || "").to_s,
+        refresh_token: (d["refreshToken"] || "").to_s,
+        expires_at: (d["expiresAt"] || 0).to_i,
+        expires_in: (d["expiresIn"] || 0).to_i,
+        scopes: Array(d["scopes"])
+      )
+    end
+  end
+
+  module_function
+
+  # Mint a client-token pair with a secret API key (server-side).
+  def mint_client_tokens(cfg, scopes: nil, ttl_sec: nil)
+    raise InvalidConfigError, "mint_client_tokens requires api_key" if cfg.api_key.nil? || cfg.api_key.empty?
+
+    base = Transport.trim_slash(cfg.base_url || DEFAULT_BASE_URL)
+    timeout = cfg.timeout && cfg.timeout.positive? ? cfg.timeout : DEFAULT_TIMEOUT
+    http = Http.new(timeout: timeout, adapter: cfg.http_adapter)
+
+    payload = { "scopes" => scopes || [] }
+    payload["ttlSec"] = ttl_sec if ttl_sec && ttl_sec.positive?
+
+    begin
+      status, raw = http.request(
+        "POST",
+        "#{base}/v2/client-tokens",
+        headers: {
+          "Accept" => "application/json",
+          "Content-Type" => "application/json",
+          "x-api-key" => cfg.api_key
+        },
+        body: JSON.generate(payload)
+      )
+    rescue StandardError => e
+      raise APIError.new(code: "NETWORK", message: "mint client tokens network error: #{e}")
+    end
+
+    unless status >= 200 && status < 300
+      raise APIError.new(
+        status: status,
+        code: "CLIENT_ERROR",
+        message: "mint client tokens failed (#{status})",
+        body: raw
+      )
+    end
+
+    TokenPair.from_hash(JSON.parse(raw))
+  end
+end

data/lib/pickpoint/routing.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pickpoint
+  class RoutingService
+    def initialize(transport)
+      @t = transport
+    end
+
+    def route(body)
+      post("/v2/route", body)
+    end
+
+    def optimized(body)
+      post("/v2/route/optimized", body)
+    end
+
+    def matrix(body)
+      post("/v2/route/matrix", body)
+    end
+
+    def locate(body)
+      post("/v2/route/locate", body)
+    end
+
+    def elevation(body)
+      post("/v2/route/elevation", body)
+    end
+
+    private
+
+    def post(path, body)
+      raw = @t.do(Transport::RequestOpts.new(method: "POST", path: path, body: body))
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    end
+  end
+end

data/lib/pickpoint/transport.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Pickpoint
+  module Transport
+    module_function
+
+    def trim_slash(s)
+      s.to_s.sub(%r{/+\z}, "")
+    end
+
+    ON_THROW = :throw
+    ON_EMPTY = :empty
+
+    RequestOpts = Struct.new(
+      :method,
+      :path,
+      :query,
+      :body,
+      :on_client_error,
+      :empty,
+      keyword_init: true
+    )
+
+    class Client
+      def initialize(base_url:, http:, auth:, max_retries:, retry_base:)
+        @base_url = base_url
+        @http = http
+        @auth = auth
+        @max_retries = max_retries
+        @retry_base = retry_base
+      end
+
+      def do(opts)
+        attempt = 0
+        auth_retried = false
+
+        loop do
+          url = build_url(opts)
+          headers = {}
+          @auth.apply!(headers)
+          body = opts.body.nil? ? nil : JSON.generate(opts.body)
+          headers["Content-Type"] = "application/json" unless body.nil?
+
+          begin
+            status, raw = @http.request(opts.method || "GET", url, headers: headers, body: body)
+          rescue StandardError => e
+            raise APIError.new(code: "NETWORK", message: "network error: #{e}") if attempt >= @max_retries
+
+            sleep_backoff(attempt)
+            attempt += 1
+            next
+          end
+
+          if status == 401
+            if !auth_retried && @auth.bearer? && @auth.refresh_after_unauthorized
+              auth_retried = true
+              next
+            end
+            raise APIError.new(status: status, code: "API_AUTH", message: "auth failed (401)", body: raw)
+          end
+
+          if [402, 403].include?(status)
+            raise APIError.new(status: status, code: "API_AUTH", message: "auth failed", body: raw)
+          end
+
+          return "" if status == 204
+
+          if status == 409
+            raise APIError.new(
+              status: 409,
+              code: "CONFLICT",
+              message: message_from_body(raw, 409),
+              body: raw
+            )
+          end
+
+          if status == 400 || (status >= 404 && status < 500)
+            return opts.empty || "" if opts.on_client_error == ON_EMPTY
+
+            code = status == 404 ? "NOT_FOUND" : "CLIENT_ERROR"
+            raise APIError.new(
+              status: status,
+              code: code,
+              message: message_from_body(raw, status),
+              body: raw
+            )
+          end
+
+          if status >= 500
+            if attempt >= @max_retries
+              raise APIError.new(
+                status: status,
+                code: "SERVER_ERROR",
+                message: "server error after retries",
+                body: raw
+              )
+            end
+            sleep_backoff(attempt)
+            attempt += 1
+            next
+          end
+
+          return raw if status >= 200 && status < 300
+
+          return opts.empty || "" if status >= 400 && status < 500 && opts.on_client_error == ON_EMPTY
+
+          raise APIError.new(
+            status: status,
+            code: "CLIENT_ERROR",
+            message: message_from_body(raw, status),
+            body: raw
+          )
+        end
+      end
+
+      private
+
+      def build_url(opts)
+        q = (opts.query || {}).reject { |_k, v| v.nil? || v.to_s.empty? }
+        path = opts.path
+        path = "#{path}?#{URI.encode_www_form(q)}" if q.any?
+        "#{@base_url}#{path}"
+      end
+
+      def message_from_body(raw, status)
+        begin
+          m = JSON.parse(raw)
+          if m.is_a?(Hash)
+            return m["message"].to_s if m["message"]
+            return m["error"].to_s if m["error"]
+          end
+        rescue JSON::ParserError
+          # fall through
+        end
+        STATUS_TEXT.fetch(status, "unknown")
+      end
+
+      def sleep_backoff(attempt)
+        base = @retry_base
+        base = DEFAULT_RETRY_BASE if base <= 0
+        base = [base, MIN_RETRY_BASE].max
+        max_delay = base * (2**[attempt, 16].min)
+        sleep(rand * max_delay)
+      end
+    end
+
+    STATUS_TEXT = {
+      400 => "Bad Request",
+      401 => "Unauthorized",
+      403 => "Forbidden",
+      404 => "Not Found",
+      409 => "Conflict",
+      500 => "Internal Server Error",
+      502 => "Bad Gateway",
+      503 => "Service Unavailable"
+    }.freeze
+  end
+end

data/lib/pickpoint/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pickpoint
+  VERSION = File.read(File.expand_path("../../VERSION", __dir__)).strip
+end

data/lib/pickpoint.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "pickpoint/version"
+require_relative "pickpoint/errors"
+require_relative "pickpoint/config"
+require_relative "pickpoint/http"
+require_relative "pickpoint/auth"
+require_relative "pickpoint/transport"
+require_relative "pickpoint/geocoding"
+require_relative "pickpoint/address"
+require_relative "pickpoint/routing"
+require_relative "pickpoint/devices"
+require_relative "pickpoint/mint"
+require_relative "pickpoint/client"
+
+# Official Ruby SDK for the Pickpoint public HTTP API.
+module Pickpoint
+end

data/pickpoint.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/pickpoint/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "pickpoint"
+  spec.version = Pickpoint::VERSION
+  spec.authors = ["Pickpoint"]
+  spec.email = ["hello@pickpoint.io"]
+
+  spec.summary = "Official Ruby SDK for Pickpoint — geocoding, address search, routing, devices"
+  spec.description = <<~DESC
+    Idiomatic Ruby client for the Pickpoint public HTTP API: geocoding, address
+    search, routing, device registry, and client-token minting. No realtime
+    tracking client in this gem.
+  DESC
+  spec.homepage = "https://github.com/pickpoint/ruby-sdk"
+  spec.license = "Apache-2.0"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = "https://pickpoint.io"
+  spec.metadata["documentation_uri"] = "https://pickpoint.io/docs"
+  spec.metadata["source_code_uri"] = "https://github.com/pickpoint/ruby-sdk"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/pickpoint/ruby-sdk/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z 2>/dev/null`.split("\x0").reject do |f|
+      f.start_with?("test/", ".github/", ".git") || f.end_with?(".gem")
+    end
+  end
+  # Fallback when not in a git repo yet
+  if spec.files.empty?
+    spec.files = Dir["lib/**/*", "LICENSE", "README.md", "VERSION", "pickpoint.gemspec"]
+  end
+
+  spec.require_paths = ["lib"]
+end