epok 0.1.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 387ff0cf39fe626399e0c9e3c3100403040a9b632c7d2a6f0b32a7831bd5fe35
-  data.tar.gz: 892468b7a7ac3cd9663e04f9aec7bdd241570db8b05c9b3f6c5baa3f0c1b0f0a
+  metadata.gz: ee8d9d659f3f1da4d0e290c2fe57173ca577ccaf6ae8c9ab5d6fb0df5a41045d
+  data.tar.gz: d075af0af60603bfc513f65f26f6656cc9a43e3e3a6dd25da47245cd96a0ea05
 SHA512:
-  metadata.gz: b300e878806a3cf7ebf3336eaae481e55576ac89e5677d1b177ef6c42e2e40a59368893aaeb34e5f78e168c437bb1f0507496900f133c8b9d6652995a0bcc52a
-  data.tar.gz: f79a5fab0614a5cbd6a146cff6693a5ffc195d9bff4d04d2551d06f76103d46ea5565e6f4a7a3efcf1b2e28cebe71071d7c228ab07905dab259b5146907a7e17
+  metadata.gz: d57ad60dcd6be25dcd1ad82039809fccc8d9039ed31439e3209fd2c85cdbe82cccf83a9e9c9846989f182c9290ccd60d440a69d3aa673f500f160cd31cf55ee2
+  data.tar.gz: 7b850241d36d95455e480cb26222233927447bab1cffe547388a53c5d0c92c6d61ae387c3c70db9aae7eb784623c38a5bf220f693f6fde06fc39a10cd01c83fb

data/.claude/skills/swarf/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: swarf
+description: Score Ruby methods by complexity against test coverage with swarf, and turn the worst rows into the next test to write. Use after writing or changing Ruby code and before calling a change done.
+---
+
+# swarf
+
+swarf scores every Ruby method with `CRAP = CC² · (1 − coverage)³ + CC` and lists them worst first. Complexity is parsed from source. Coverage is recorded by a probe loaded into the test run and stored in `.swarf/coverage.json`, so scoring works without setup but coverage needs a test run.
+
+## The loop
+
+1. Run the suite with the probe loaded (see Setup if unsure):
+
+   ```
+   bundle exec rspec          # or: bundle exec rake test
+   ```
+
+2. Score the files you touched, not the whole project:
+
+   ```
+   git diff --name-only --diff-filter=d main -- '*.rb' | xargs bundle exec swarf
+   ```
+
+   Named paths are always scored, even under `test/`, `db/` or a `.swarfignore` pattern.
+
+3. Take the top rows and act on the Evidence column (next section). Write or extend the test, re-run the suite, score again.
+
+4. Stop when the touched methods sit at `CRAP = CC` with `Cov% 100.0`. Nothing you test pulls a score under its CC. If a score is too high at full coverage, that is complexity, which is a refactor question, not a testing one. Do not split methods to chase the number.
+
+Before saying a change is done, run step 2 and report the top rows.
+
+## Reading a row
+
+```
+Method          CC    Cov%   CRAP      Evidence  Location
+Cart#checkout    6    0.0%  42.00  never called  lib/cart.rb:31
+Cart#discount    4   50.0%   6.00        3/6 br  lib/cart.rb:24
+```
+
+| Evidence       | Meaning                                      | Do                                                            |
+| -------------- | -------------------------------------------- | ------------------------------------------------------------- |
+| `never called` | A VM call count of zero. No test reaches it. | Write a test that calls it.                                   |
+| `3/6 br`       | 3 of 6 branch outcomes ran.                  | Extend a test to the untaken outcomes.                        |
+| `1/1 ln`       | No branches, so lines are the whole truth.   | Nothing, at 100%.                                             |
+| `no data`      | No run has been recorded for this file.      | The probe is not loaded, or the suite has not run. Fix Setup. |
+| `stale`        | The file changed after it was measured.      | Re-run the suite, then score again.                           |
+
+`no data` and `stale` both score at the `CC² + CC` floor rather than guess. They are also counted per file under the table, because the fix is per file.
+
+A `never called` on a method a test clearly exercises means the test ran without the probe, or the probe loaded after the file. Check Setup before writing a duplicate test.
+
+## Setup
+
+The probe must load before the code under test, because `Coverage` only sees files loaded after it starts. One line, placed first:
+
+- **RSpec**: first line of `.rspec`: `--require swarf/probe`
+- **Minitest**: first line of `test/test_helper.rb`: `require "swarf/probe"`
+- **Rails**: in `test/test_helper.rb`, after `require "bundler/setup"` and before `require_relative "../config/environment"`. Below the environment require, the whole app is invisible to it.
+- **Anything**: `RUBYOPT="-rswarf/probe" bundle exec rake test`
+
+Add `.swarf/` to `.gitignore`. Runs merge, so a single spec file adds to what earlier runs proved; nothing is erased until the file's bytes change.
+
+Do not run swarf's probe alongside SimpleCov. Ruby allows one `Coverage.start` per process; if SimpleCov started first, swarf warns and records nothing.
+
+## Commands
+
+```
+bundle exec swarf                       # whole project, worst 20
+bundle exec swarf lib/ app/             # directories
+bundle exec swarf app/models/cart.rb    # one file
+bundle exec swarf --limit 0             # every row
+bundle exec swarf --ignore "app/legacy/**"
+bundle exec swarf --all                 # ignore nothing, including db/ and .swarfignore
+SWARF_DIR=/tmp/swarf bundle exec swarf  # store elsewhere; set for the test run too
+```
+
+swarf's CC counts `if`, `unless`, `while`, `until`, `for`, `when`, `in`, `rescue`, `&&`, `||` and `&.`, not blocks, so it will not match RuboCop's. Methods made by `define_method` are not seen.

data/.gitignore

@@ -7,3 +7,4 @@
 /spec/reports/
 /tmp/
 /test/fixtures/
+.swarf/

data/CLAUDE.md

@@ -0,0 +1,47 @@
+# Epok
+
+Ruby gem wrapping the GCBA EPOk API (https://epok.buenosaires.gob.ar).
+No runtime dependencies beyond the standard library.
+
+## Development
+
+```
+bundle install
+bundle exec rake test     # records VCR cassettes into test/fixtures on first run
+bundle exec swarf lib/    # complexity vs. coverage report, worst first
+```
+
+Cassettes are gitignored, so the first test run hits the live API.
+The API rejects curl's default User-Agent, but Ruby's Net::HTTP works fine.
+
+## API notes
+
+Official docs are Swagger specs on the city's 3scale portal. The HTML at
+https://datosabiertos-apis.buenosaires.gob.ar/BA_Root/Documentacion is
+JavaScript-rendered; fetch the JSON directly:
+
+- Index: https://datosabiertos-apis.buenosaires.gob.ar/api_docs/services.json
+- EPOk ("Busquedas de Lugares"): .../api_docs/services/10.json
+- USIG Geocoder: .../api_docs/services/8.json
+- Datos Útiles: .../api_docs/services/9.json
+
+The specs list `datosabiertos-*-apis.buenosaires.gob.ar` hosts that return
+404. The live hosts are `epok.buenosaires.gob.ar` for EPOk and
+`ws.usig.buenosaires.gob.ar` for USIG (REST index with docs at
+https://ws.usig.buenosaires.gob.ar/rest/).
+
+- `/buscar/` also takes `categoria` (comma-separated), `clase`, `bbox`,
+  `start`, `limit` and `totalFull`.
+- `/reverseGeocoderLugares/` takes `srid` (default 4326) and `radio`
+  (default 1 metre, hence our 500 default).
+- Unknown ids return `200 {}`, unknown categories return an empty list.
+- Object coordinates are projected (Gauss-Krüger Buenos Aires). USIG's
+  `/rest/convertir_coordenadas` turns them into longitude and latitude.
+- `ws.usig.buenosaires.gob.ar/datos_utiles?x=&y=` answers with empty strings
+  outside the city; `Epok.datos_utiles` turns those into nil.
+- `servicios.usig.buenosaires.gob.ar/normalizar/?direccion=&geocodificar=true`
+  matches across the whole AMBA, CABA first. Coordinates come back as
+  strings for CABA and floats elsewhere. No match is `200` with an empty
+  list and an `errorMessage`; `Epok.geocode` raises NotFound with it.
+- A December 2025 city report says "API USIG" is being replaced by
+  "API Servicios Geo" during 2026. The USIG hosts above may move.

data/Gemfile

@@ -3,3 +3,6 @@ source "https://rubygems.org"
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 gemspec
+
+gem "irb", group: :development
+gem "swarf", group: :development

data/Gemfile.lock

@@ -1,47 +1,90 @@
 PATH
   remote: .
   specs:
-    epok (0.1.0)
+    epok (0.5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.6.0)
-      public_suffix (>= 2.0.2, < 4.0)
-    ansi (1.5.0)
-    builder (3.2.3)
-    byebug (11.0.1)
-    crack (0.4.3)
-      safe_yaml (~> 1.0.0)
-    hashdiff (0.3.9)
-    minitest (5.11.3)
-    minitest-reporters (1.3.6)
-      ansi
-      builder
-      minitest (>= 5.0)
-      ruby-progressbar
-    public_suffix (3.0.3)
-    rake (10.5.0)
-    ruby-progressbar (1.10.0)
-    safe_yaml (1.0.5)
-    vcr (4.0.0)
-    webmock (3.5.1)
-      addressable (>= 2.3.6)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    bigdecimal (4.1.3)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    erb (6.0.7)
+    hashdiff (1.2.1)
+    io-console (0.9.3)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    logger (1.7.0)
+    minitest (5.27.0)
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    rake (13.4.2)
+    rbs (4.2.0)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (8.0.0)
+      erb
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
+      tsort
+    reline (0.7.0)
+      io-console (~> 0.5)
+    rexml (3.4.4)
+    swarf (0.2.0)
+    tsort (0.2.0)
+    vcr (6.4.0)
+    webmock (3.26.4)
+      addressable (>= 2.8.0)
       crack (>= 0.3.2)
-      hashdiff
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
+  arm64-darwin-23
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.17)
-  byebug
   epok!
+  irb
   minitest (~> 5.0)
-  minitest-reporters (~> 1.3, >= 1.3.6)
-  rake (~> 10.0)
-  vcr (~> 4.0)
+  rake (~> 13.0)
+  swarf
+  vcr (~> 6.0)
   webmock (~> 3.5, >= 3.5.1)
 
+CHECKSUMS
+  addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
+  bigdecimal (4.1.3) sha256=61ebe1e5e559bdc3cc6f2c0ee7f427321fc838f59611c294356eb04d6e21cf66
+  crack (1.0.1) sha256=ff4a10390cd31d66440b7524eb1841874db86201d5b70032028553130b6d4c7e
+  epok (0.5.0)
+  erb (6.0.7) sha256=c5ca6dc25b0ef974a44dc8f59fe847577122483b1968a38dec305c60bf91ee92
+  hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
+  io-console (0.9.3) sha256=f555049461b0afb78a5448b5be8e7c7b48371347cd48abfc22814764160000dd
+  irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  minitest (5.27.0) sha256=2d3b17f8a36fe7801c1adcffdbc38233b938eb0b4966e97a6739055a45fa77d5
+  pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  rbs (4.2.0) sha256=51f7b886dcc05bc09e10b901daa6a81829f6adc03101d6ca9ea4aac6103e0674
+  rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
+  reline (0.7.0) sha256=5b012d8e55dbf9d450f12bde2cf7d15ff546ae80b3f8f3b30e570d431815583d
+  rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
+  swarf (0.2.0) sha256=b4306a244fe4b096cfe263e452e666156856eac2467ae5d770639ef11388b375
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+  vcr (6.4.0) sha256=077ac92cc16efc5904eb90492a18153b5e6ca5398046d8a249a7c96a9ea24ae6
+  webmock (3.26.4) sha256=8d8da206d217ebe6968cfb09c77f4533c23074e1432bad865f3994eacbaad50d
+
 BUNDLED WITH
-   1.17.2
+  4.0.20

data/README.md

@@ -1,15 +1,13 @@
 # Epok
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/epok`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+GCBA EPOk wrapper to query indexed geographic objects.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'epok'
+gem "epok"
 ```
 
 And then execute:
@@ -22,7 +20,72 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+"I'm at Callao y Corrientes, what's around me?" in five requests:
+
+```ruby
+require "epok"
+
+# 1. Turn a typed address into coordinates.
+here = Epok.geocode("callao y corrientes").first
+puts "You are at #{here.address}"
+
+# 2. Which neighbourhood and comuna is that?
+area = Epok.datos_utiles(here.location)
+puts "That's #{area.barrio}, #{area.comuna}"
+
+# 3. What's within 300 metres, by category?
+nearby = Epok.geocoder(here.location, %w[estaciones_de_subte farmacias], radius: 300)
+nearby.sort_by(&:distance).first(5).each do |place|
+  puts "  #{place.distance.round} m  #{place.name} (#{place.kind})"
+end
+
+# 4. Drill into one: full record and coordinates for a map pin.
+closest = nearby.min_by(&:distance)
+puts "Pin: #{closest.location.y}, #{closest.location.x}"
+closest.content.each { |key, value| puts "  #{key}: #{value}" }
+```
+
+```
+You are at CALLAO AV. y CORRIENTES AV., CABA
+That's San Nicolas, Comuna 3
+  3 m  CALLAO - MAESTRO ALFREDO BRAVO (Línea B) (Estación de Subte (Metro))
+  42 m  Farmacia en CORRIENTES AV. 1820 (Farmacia)
+  73 m  Farmacia en CORRIENTES AV. 1835 (Farmacia)
+  98 m  Farmacia en CALLAO AV. 477 (Farmacia)
+  111 m  Farmacia en CORRIENTES AV. 1880 (Farmacia)
+Pin: -34.604419, -58.392318
+  Nombre: CALLAO - MAESTRO ALFREDO BRAVO (Línea B)
+  Línea: B
+  Estado: Estación Malabia cerrada por obras de renovación integral.
+  Cabeceras: J. M. de Rosas - L. N. Alem
+  Tiempo: 27 min.
+```
+
+Steps 1 to 3 are one request each; step 4 is two (the record, then the coordinate conversion). The content hash is whatever the city publishes for that category: subway stations carry line, status and travel time, pharmacies carry phone and delivery details.
+
+### The rest
+
+**Search by text**, optionally filtered by category and capped:
+
+```ruby
+Epok.search("cgp", categories: "sedes_de_comunas", limit: 3).map(&:name)
+# => ["Sede Comunal 4", "Sede Comunal 9", "Sede Comunal 10"]
+```
+
+**Categories** are what the geocoder and the search filter take. There are 167, each with an id, a display name and a description:
+
+```ruby
+Epok.categories.find { |c| c.id == "farmacias" }
+# => #<struct Epok::Category id="farmacias", name="Farmacias", description="">
+```
+
+**Collections** from `search` and `geocoder` are `Enumerable` and lazy: nothing is requested until you iterate.
+
+**Objects** know their `id`, `name`, `kind`, `category` and, from the geocoder, `distance` in metres straight from the listing. `content`, `normalized_address` and `location` fetch the full record on first use; `location` also converts the city's projected coordinates through USIG. `Epok::Object.new("farmacias|1082")` looks one up by id.
+
+**Locations** are `Epok::Location.new(x: longitude, y: latitude)`. `geocode` returns every match across the metro area, city first, as `Address` structs with `address`, `partido`, `localidad` and `location`. `datos_utiles` returns nil for the city fields outside CABA and fills `partido_amba` and `localidad_amba` instead.
+
+**Errors**: every request failure raises `Epok::Error`. An unknown id or address raises `Epok::NotFound`.
 
 ## Development
 
@@ -40,4 +103,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Epok project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/arzezak/epok/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Epok project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/arzezak/epok/blob/main/CODE_OF_CONDUCT.md).

data/bin/console

@@ -4,6 +4,4 @@ require "bundler/setup"
 require "epok"
 require "irb"
 
-@obelisco = Epok::Location.new(x: -58.381570, y: -34.603738)
-
 IRB.start(__FILE__)

data/epok.gemspec

@@ -17,10 +17,8 @@ Gem::Specification.new do |spec|
   spec.files = `git ls-files`.split("\n")
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.17"
   spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "minitest-reporters", "~> 1.3", ">= 1.3.6"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "vcr", "~> 4.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "vcr", "~> 6.0"
   spec.add_development_dependency "webmock", "~> 3.5", ">= 3.5.1"
 end

data/lib/epok/api.rb

@@ -2,23 +2,75 @@ require "net/http"
 require "json"
 
 module Epok
+  class Error < StandardError; end
+  class NotFound < Error; end
+
   class API
-    BASE_URL = "epok.buenosaires.gob.ar"
+    EPOK_URL = "https://epok.buenosaires.gob.ar".freeze
+    USIG_URL = "https://ws.usig.buenosaires.gob.ar".freeze
+    USIG_SERVICES_URL = "https://servicios.usig.buenosaires.gob.ar".freeze
+    TIMEOUT = 10
 
     def self.object(id)
-      response = Net::HTTP.get_response(BASE_URL, "/getObjectContent/?id=#{id}")
-      JSON.parse(response.body)
+      object = get(EPOK_URL, "/getObjectContent/", id: id)
+      raise NotFound, "no object with id #{id}" if object.empty?
+
+      object
+    end
+
+    def self.search(query, categories = nil, limit = nil)
+      params = { texto: query, categoria: categories, limit: limit }.compact
+
+      get(EPOK_URL, "/buscar/", params)["instancias"]
+    end
+
+    def self.geocoder(x, y, categories, radius)
+      get(EPOK_URL, "/reverseGeocoderLugares/",
+        x: x, y: y, categorias: categories, radio: radius)["instancias"]
+    end
+
+    def self.categories
+      get(EPOK_URL, "/getCategorias/", {})["categorias"]
     end
 
-    def self.search(query)
-      response = Net::HTTP.get_response(BASE_URL, "/buscar/?texto=#{query}")
-      JSON.parse(response.body)["instancias"]
+    def self.geocode(text)
+      response = get(USIG_SERVICES_URL, "/normalizar/", direccion: text, geocodificar: true)
+      addresses = response["direccionesNormalizadas"]
+      raise NotFound, response["errorMessage"] if addresses.empty?
+
+      addresses
+    end
+
+    def self.datos_utiles(x, y)
+      get(USIG_URL, "/datos_utiles", x: x, y: y)
+    end
+
+    # Converts EPOk's projected coordinates (Gauss-Krüger Buenos Aires) to
+    # longitude and latitude through the city's USIG service.
+    def self.to_lonlat(x, y)
+      response = get(USIG_URL, "/rest/convertir_coordenadas", x: x, y: y, output: "lonlat")
+      raise Error, "USIG could not convert (#{x}, #{y})" unless response["tipo_resultado"] == "Ok"
+
+      response["resultado"].values_at("x", "y").map(&:to_f)
     end
 
-    def self.geocoder(x, y, categories)
-      response = Net::HTTP.get_response(BASE_URL,
-        "/reverseGeocoderLugares/?x=#{x}&y=#{y}&categorias=#{categories}&radio=500")
-      JSON.parse(response.body)["instancias"]
+    def self.get(host, path, params)
+      uri = URI("#{host}#{path}")
+      uri.query = URI.encode_www_form(params)
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+        open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+        http.get(uri.request_uri)
+      end
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Error, "EPOk responded #{response.code} to #{uri}"
+      end
+
+      JSON.parse(response.body)
+    rescue SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError, JSON::ParserError => e
+      raise Error, "#{e.class}: #{e.message}"
     end
+    private_class_method :get
   end
 end

data/lib/epok/collection.rb

@@ -2,22 +2,18 @@ module Epok
   class Collection
     include Enumerable
 
-    attr_reader :data
-
-    def initialize(data, id = "id")
-      @data = collection(data, id)
+    def initialize(&fetch)
+      @fetch = fetch
     end
 
     def each(&block)
-      data.each(&block)
+      objects.each(&block)
     end
 
     private
 
-    def collection(data, id)
-      data.map do |item|
-        Object.new(item[id])
-      end
+    def objects
+      @objects ||= @fetch.call.map { |item| Object.new(item) }
     end
   end
 end

data/lib/epok/object.rb

@@ -1,22 +1,52 @@
 module Epok
   class Object
-    attr_reader :id
+    attr_reader :id, :distance
 
-    def initialize(id)
-      @id = id
+    # Accepts either an id ("farmacias|1082") or a result hash from a search
+    # or geocoder listing. Listing attributes are available immediately; the
+    # full content is fetched on first use.
+    def initialize(attributes)
+      attributes = { "id" => attributes } if attributes.is_a?(String)
+
+      @id = attributes.fetch("id")
+      @name = attributes["nombre"]&.strip
+      @kind = attributes["clase"]
+      @distance = attributes["distancia"]&.to_f
     end
 
     def name
-      content["Nombre"]
+      @name ||= content["Nombre"]
+    end
+
+    def kind
+      @kind ||= object["clase"]
+    end
+
+    def category
+      id.split("|").first
     end
 
     def normalized_address
       object["direccionNormalizada"]
     end
 
+    # Longitude and latitude as a Location, or nil when EPOk has no
+    # centroid for the object. Costs one extra request the first time.
+    def location
+      return @location if defined?(@location)
+
+      centroid = object.dig("ubicacion", "centroide")
+      @location = centroid && begin
+        x, y = centroid[/\(([^)]*)\)/, 1].split.map(&:to_f)
+        lon, lat = API.to_lonlat(x, y)
+        Location.new(x: lon, y: lat)
+      end
+    end
+
     def content
       object["contenido"].each_with_object({}) do |entry, hash|
         name, value = entry.values_at("nombre", "valor")
+        value = value.strip
         hash[name] = value unless value.empty?
       end
     end
@@ -24,7 +54,7 @@ module Epok
     private
 
     def object
-      API.object(id)
+      @object ||= API.object(id)
     end
   end
 end

data/lib/epok/version.rb

@@ -1,3 +1,3 @@
 module Epok
-  VERSION = "0.1.1"
+  VERSION = "0.5.0"
 end

data/lib/epok.rb

@@ -1,17 +1,65 @@
 require "epok/api"
-require "epok/collectable"
 require "epok/collection"
-require "epok/geocoder"
 require "epok/object"
-require "epok/search"
 require "epok/version"
 
 module Epok
-  def self.search(query)
-    Search.new(query)
+  Location = Struct.new(:x, :y, keyword_init: true)
+  Category = Struct.new(:id, :name, :description, keyword_init: true)
+  DatosUtiles = Struct.new(
+    :barrio, :comuna, :comisaria, :comisaria_vecinal,
+    :area_hospitalaria, :region_sanitaria, :distrito_escolar,
+    :partido_amba, :localidad_amba,
+    keyword_init: true
+  )
+
+  Address = Struct.new(:address, :partido, :localidad, :location, keyword_init: true)
+
+  DEFAULT_RADIUS = 500
+
+  def self.search(query, categories: nil, limit: nil)
+    categories = Array(categories).join(",") if categories
+
+    Collection.new { API.search(query, categories, limit) }
+  end
+
+  def self.geocoder(location, categories, radius: DEFAULT_RADIUS)
+    categories = Array(categories).join(",")
+
+    Collection.new { API.geocoder(location.x, location.y, categories, radius) }
+  end
+
+  def self.geocode(text)
+    API.geocode(text).map do |address|
+      x, y = address["coordenadas"].values_at("x", "y").map(&:to_f)
+
+      Address.new(
+        address: address["direccion"],
+        partido: address["nombre_partido"],
+        localidad: address["nombre_localidad"],
+        location: Location.new(x: x, y: y)
+      )
+    end
+  end
+
+  def self.datos_utiles(location)
+    datos = API.datos_utiles(location.x, location.y)
+
+    DatosUtiles.new(
+      DatosUtiles.members.to_h do |member|
+        value = datos[member.to_s].to_s.strip.squeeze(" ")
+        [member, value.empty? ? nil : value]
+      end
+    )
   end
 
-  def self.geocoder(location, categories)
-    Geocoder.new(location, categories)
+  def self.categories
+    API.categories.map do |category|
+      Category.new(
+        id: category["nombre_normalizado"],
+        name: category["nombre"],
+        description: category["descripcion"]
+      )
+    end
   end
 end

data/test/epok/api_test.rb

@@ -0,0 +1,65 @@
+require "test_helper"
+
+module Epok
+  class APITest < Minitest::Test
+    include WebMock::API
+
+    def setup
+      VCR.eject_cassette
+      VCR.turn_off!
+    end
+
+    def teardown
+      WebMock.reset!
+      VCR.turn_on!
+    end
+
+    def test_that_a_server_error_raises
+      stub_request(:get, /epok/).to_return(status: 500, body: "boom")
+
+      error = assert_raises(Error) { Epok.search("x").first }
+      assert_match "500", error.message
+    end
+
+    def test_that_a_timeout_raises
+      stub_request(:get, /epok/).to_timeout
+
+      assert_raises(Error) { Epok.categories }
+    end
+
+    def test_that_a_non_json_body_raises
+      stub_request(:get, /epok/).to_return(status: 200, body: "<html>")
+
+      assert_raises(Error) { Epok.search("x").first }
+    end
+
+    def test_that_a_missing_object_raises_not_found
+      stub_request(:get, /getObjectContent/).to_return(status: 200, body: "{}")
+
+      assert_raises(NotFound) { Object.new("nope|1").content }
+    end
+
+    def test_that_an_object_without_a_centroid_has_no_location
+      stub_request(:get, /getObjectContent/)
+        .to_return(status: 200, body: '{"contenido": [], "ubicacion": null}')
+
+      object = Object.new("espacios_verdes_publicos|1")
+
+      assert_nil object.location
+      assert_nil object.location
+    end
+
+    def test_that_a_failed_coordinate_conversion_raises
+      stub_request(:get, /getObjectContent/)
+        .to_return(status: 200, body: '{"ubicacion": {"centroide": "POINT (1 2)"}}')
+      stub_request(:get, /usig/)
+        .to_return(status: 200, body: '{"tipo_resultado":"Error","resultado":{"x":"","y":""}}')
+
+      assert_raises(Error) { Object.new("x|1").location }
+    end
+
+    def test_that_not_found_is_an_error
+      assert_operator NotFound, :<, Error
+    end
+  end
+end

data/test/epok/categories_test.rb

@@ -0,0 +1,26 @@
+require "test_helper"
+
+module Epok
+  class CategoriesTest < Minitest::Test
+    def setup
+      VCR.insert_cassette("categories")
+    end
+
+    def teardown
+      VCR.eject_cassette("categories")
+    end
+
+    def test_that_categories_are_listed
+      categories = Epok.categories
+
+      assert_operator categories.size, :>, 100
+      assert categories.all? { |category| category.is_a?(Category) }
+    end
+
+    def test_that_a_category_has_an_id_and_a_name
+      pharmacies = Epok.categories.find { |category| category.id == "farmacias" }
+
+      assert_equal "Farmacias", pharmacies.name
+    end
+  end
+end

data/test/epok/collection_test.rb

@@ -0,0 +1,22 @@
+require "test_helper"
+
+module Epok
+  class CollectionTest < Minitest::Test
+    def test_that_a_collection_is_enumerable
+      collection = Collection.new { [{"id" => "a|1"}, {"id" => "a|2"}] }
+
+      assert_equal ["a|1", "a|2"], collection.map(&:id)
+      assert_equal 2, collection.count
+    end
+
+    def test_that_a_collection_fetches_lazily_and_once
+      calls = 0
+      collection = Collection.new { calls += 1; [{"id" => "a|1"}] }
+
+      assert_equal 0, calls
+      collection.first
+      collection.to_a
+      assert_equal 1, calls
+    end
+  end
+end

data/test/epok/datos_utiles_test.rb

@@ -0,0 +1,39 @@
+require "test_helper"
+
+module Epok
+  class DatosUtilesTest < Minitest::Test
+    def setup
+      VCR.insert_cassette("datos_utiles")
+    end
+
+    def teardown
+      VCR.eject_cassette("datos_utiles")
+    end
+
+    def test_that_datos_utiles_returns_the_barrio_and_comuna
+      datos = Epok.datos_utiles(Location.new(x: -58.381570, y: -34.603738))
+
+      assert_equal "San Nicolas", datos.barrio
+      assert_equal "Comuna 1", datos.comuna
+    end
+
+    def test_that_datos_utiles_returns_the_other_jurisdictions
+      datos = Epok.datos_utiles(Location.new(x: -58.381570, y: -34.603738))
+
+      assert_equal "3", datos.comisaria
+      assert_equal "1B", datos.comisaria_vecinal
+      assert_equal "HTAL. DR. J.M. RAMOS MEJÍA", datos.area_hospitalaria
+      assert_equal "I (Este)", datos.region_sanitaria
+      assert_equal "Distrito Escolar I", datos.distrito_escolar
+    end
+
+    def test_that_outside_the_city_fields_are_nil_and_amba_is_filled
+      datos = Epok.datos_utiles(Location.new(x: -58.60, y: -34.60))
+
+      assert_nil datos.barrio
+      assert_nil datos.comuna
+      assert_equal "Tres de Febrero", datos.partido_amba
+      assert_equal "Ciudad Jardín Lomas de El Palomar", datos.localidad_amba
+    end
+  end
+end

data/test/epok/geocode_test.rb

@@ -0,0 +1,36 @@
+require "test_helper"
+
+module Epok
+  class GeocodeTest < Minitest::Test
+    def setup
+      VCR.insert_cassette("geocode")
+    end
+
+    def teardown
+      VCR.eject_cassette("geocode")
+    end
+
+    def test_that_an_address_is_normalized_and_located
+      address = Epok.geocode("cabildo 1234").first
+
+      assert_equal "CABILDO AV. 1234, CABA", address.address
+      assert_in_delta(-58.448466, address.location.x)
+      assert_in_delta(-34.568290, address.location.y)
+    end
+
+    def test_that_an_address_has_a_partido_and_localidad
+      addresses = Epok.geocode("cabildo 1234")
+
+      assert_equal "CABA", addresses.first.partido
+      assert_equal "CABA", addresses.first.localidad
+      assert_equal "La Matanza", addresses[1].partido
+      assert_equal "Villa Madero", addresses[1].localidad
+    end
+
+    def test_that_an_unknown_address_raises_not_found
+      error = assert_raises(NotFound) { Epok.geocode("xyzzy 999") }
+
+      assert_equal "Calle inexistente: xyzzy 999", error.message
+    end
+  end
+end

data/test/epok/geocoder_test.rb

@@ -3,7 +3,7 @@ require "test_helper"
 module Epok
   class GeocoderTest < Minitest::Test
     def setup
-      VCR.insert_cassette("geocoder", record: :new_episodes)
+      VCR.insert_cassette("geocoder")
     end
 
     def teardown
@@ -18,12 +18,32 @@ module Epok
       assert_match "Línea D", result.name
     end
 
+    def test_that_geocoder_results_have_a_distance
+      assert_operator result.distance, :<, 500
+    end
+
+    def test_that_geocoder_accepts_a_radius
+      near = Epok.geocoder(obelisco, "estaciones_de_subte", radius: 100)
+      far = Epok.geocoder(obelisco, "estaciones_de_subte", radius: 1000)
+
+      assert_operator near.count, :<, far.count
+      assert near.all? { |station| station.distance <= 100 }
+    end
+
+    def test_that_geocoder_accepts_several_categories
+      results = Epok.geocoder(obelisco, %w[estaciones_de_subte farmacias])
+
+      assert_equal %w[estaciones_de_subte farmacias].sort, results.map(&:category).uniq.sort
+    end
+
     private
 
     def result
-      obelisco = Location.new(x: -58.381570, y: -34.603738)
-      results = Geocoder.new(obelisco, "estaciones_de_subte")
-      results.first
+      Epok.geocoder(obelisco, "estaciones_de_subte").first
+    end
+
+    def obelisco
+      Location.new(x: -58.381570, y: -34.603738)
     end
   end
 end

data/test/epok/object_test.rb

@@ -11,27 +11,68 @@ module Epok
     end
 
     def test_that_an_object_has_a_name
-      assert_equal "Calesita del Parque Saavedra", object.name
+      assert_equal "BIBLIOTECA ANMAT", object.name
+    end
+
+    def test_that_an_object_has_a_kind
+      assert_equal "Dependencias Culturales", object.kind
+    end
+
+    def test_that_an_object_has_a_category
+      assert_equal "dependencias_culturales", object.category
     end
 
     def test_that_an_object_has_a_normalized_address
-      assert_equal "GARCIA DEL RIO y CONDE", object.normalized_address
+      assert_equal "DE MAYO AV. 869", object.normalized_address
+    end
+
+    def test_that_an_object_has_a_location
+      location = object.location
+
+      assert_instance_of Location, location
+      assert_in_delta(-58.38, location.x, 0.01)
+      assert_in_delta(-34.61, location.y, 0.01)
     end
 
     def test_that_an_object_has_content
       expected_content = {
-        "Nombre" => "Calesita del Parque Saavedra",
-        "Dirección" => "GARCIA DEL RIO y CONDE (CP 1430) - Saavedra - Comuna 12",
-        "Actividad Principal" => "Calesita",
-        "Días y Horarios" => "Todos los días de 10:00 a 12:00 y de 14:00 a 19:30.",
-        "Observaciones" => "Los días de lluvia la calesita se encuentra cerrada.",
-        "Sector" => "Privado",
-        "Público" => "Niños"
+        "Nombre" => "BIBLIOTECA ANMAT",
+        "Categoria" => "BIBLIOTECA",
+        "Subcategoria" => "ESPECIALIZADA GUBERNAMENTAL",
+        "Teléfonos" => "54.011 4340-0800 INT. 1047 FAX 54.011 4340-0800 INT. 1048",
+        "E-Mail" => "<a href=\"mailto:NDURAND@ANMAT.GOV.AR\">NDURAND@ANMAT.GOV.AR</a>",
+        "Página WEB" => "<a href=\"http://WWW.ANMAT.GOV.AR\" target=\"_blank\">WWW.ANMAT.GOV.AR</a>",
+        "Dependencia" => "ADMINISTRACION NACIONAL DE MEDICAMENTOS Y TECNOLOGIA MEDICA ANMAT",
+        "Sector" => "PUBLICO",
+        "Dirección" => "DE MAYO AV. 869",
+        "Barrio" => "MONSERRAT",
+        "Comuna" => "Comuna 1"
       }
 
       assert_equal expected_content, object.content
     end
 
+    def test_that_listing_attributes_do_not_fetch
+      object = Object.new(
+        "id" => "farmacias|1082",
+        "nombre" => "Farmacia en CERRITO 342 ",
+        "clase" => "Farmacia",
+        "distancia" => "112.31"
+      )
+
+      VCR.eject_cassette
+      VCR.turned_off do
+        assert_equal "Farmacia en CERRITO 342", object.name
+        assert_equal "Farmacia", object.kind
+        assert_equal "farmacias", object.category
+        assert_in_delta 112.31, object.distance
+      end
+    end
+
+    def test_that_an_object_built_from_an_id_has_no_distance
+      assert_nil object.distance
+    end
+
     private
 
     def object

data/test/epok/search_test.rb

@@ -18,11 +18,30 @@ module Epok
       assert_match "San Miguel de Garicoits", result.name
     end
 
+    def test_that_search_encodes_the_query
+      assert_match "Peña", Epok.search("plaza peña").first.name
+    end
+
+    def test_that_search_filters_by_category
+      results = Epok.search("san martin", categories: "estaciones_de_subte")
+
+      assert_equal ["estaciones_de_subte"], results.map(&:category).uniq
+    end
+
+    def test_that_search_filters_by_several_categories
+      results = Epok.search("san martin", categories: %w[estaciones_de_subte estaciones_de_ferrocarril])
+
+      assert_equal %w[estaciones_de_ferrocarril estaciones_de_subte], results.map(&:category).uniq.sort
+    end
+
+    def test_that_search_limits_results
+      assert_equal 2, Epok.search("san martin", limit: 2).count
+    end
+
     private
 
     def result
-      results = Search.new("garicoits")
-      results.first
+      Epok.search("garicoits").first
     end
   end
 end

data/test/epok_test.rb

@@ -1,15 +1,13 @@
 require "test_helper"
 
 class EpokTest < Minitest::Test
-  def test_that_it_has_a_version_number
-    refute_nil Epok::VERSION
+  def test_that_search_builds_a_collection
+    assert_instance_of Epok::Collection, Epok.search("garicoits")
   end
 
-  def test_responds_to_search
-    assert_respond_to Epok, :search
-  end
+  def test_that_geocoder_builds_a_collection
+    obelisco = Epok::Location.new(x: -58.381570, y: -34.603738)
 
-  def test_responds_to_geocoder
-    assert_respond_to Epok, :geocoder
+    assert_instance_of Epok::Collection, Epok.geocoder(obelisco, "farmacias")
   end
 end

data/test/test_helper.rb

@@ -1,13 +1,13 @@
+require "swarf/probe"
+
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
 require "epok"
 require "minitest/autorun"
-require "minitest/reporters"
 require "vcr"
 
-Minitest::Reporters.use!
-
 VCR.configure do |config|
   config.cassette_library_dir = "test/fixtures"
   config.hook_into :webmock
+  config.default_cassette_options = { record: :new_episodes }
 end

metadata

@@ -1,29 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: epok
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Ariel Rzezak
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.17'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.17'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -38,54 +23,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: minitest-reporters
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.3.6
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.3.6
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -113,7 +78,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/skills/swarf/SKILL.md"
 - ".gitignore"
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -125,12 +92,14 @@ files:
 - epok.gemspec
 - lib/epok.rb
 - lib/epok/api.rb
-- lib/epok/collectable.rb
 - lib/epok/collection.rb
-- lib/epok/geocoder.rb
 - lib/epok/object.rb
-- lib/epok/search.rb
 - lib/epok/version.rb
+- test/epok/api_test.rb
+- test/epok/categories_test.rb
+- test/epok/collection_test.rb
+- test/epok/datos_utiles_test.rb
+- test/epok/geocode_test.rb
 - test/epok/geocoder_test.rb
 - test/epok/object_test.rb
 - test/epok/search_test.rb
@@ -140,7 +109,6 @@ homepage: https://github.com/arzezak/epok
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -155,8 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.1
-signing_key: 
+rubygems_version: 4.0.20
 specification_version: 4
 summary: GCBA EPOk wrapper.
 test_files: []

data/lib/epok/collectable.rb

@@ -1,17 +0,0 @@
-require "forwardable"
-
-module Epok
-  module Collectable
-    def self.included(base)
-      base.class_eval do
-        extend Forwardable
-
-        def_delegators :results, :entries, :first
-      end
-    end
-
-    def collection(object)
-      Collection.new object
-    end
-  end
-end

data/lib/epok/geocoder.rb

@@ -1,21 +0,0 @@
-module Epok
-  Location = Struct.new(:x, :y, keyword_init: true)
-
-  class Geocoder
-    include Collectable
-
-    attr_reader :x, :y, :categories
-
-    def initialize(location, categories)
-      @x = location.x
-      @y = location.y
-      @categories = categories
-    end
-
-    private
-
-    def results
-      collection API.geocoder(x, y, categories)
-    end
-  end
-end

data/lib/epok/search.rb

@@ -1,17 +0,0 @@
-module Epok
-  class Search
-    include Collectable
-
-    attr_reader :query
-
-    def initialize(query)
-      @query = query
-    end
-
-    private
-
-    def results
-      collection API.search(query)
-    end
-  end
-end