Add SMO-SEPA-KiWIS Ruby gem

07 Ruby Exchange Gems/SMO-SEPA-KiWIS/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+*.csv
+.ruby-lsp/
+.DS_Store
+Gemfile.lock

07 Ruby Exchange Gems/SMO-SEPA-KiWIS/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.1] - 2025-05-03
+
+### Changed
+
+- Updated gem description and author attribution.
+
+## [0.1.0] - 2024-01-01
+
+### Added
+
+- Initial release.
+- `Client` with six public methods: `rainfall_stations`, `rainfall_15min_timeseries`,
+  `rainfall_15min_inventory`, `timeseries_values`, `rainfall_15min_inventory_to_csv`,
+  `timeseries_values_to_csv`.
+- `Station`, `Timeseries`, and `Value` structs.
+- `ResponseParser` for KiWIS column-array JSON format.
+- `ApiError` and `ParseError` error classes.
+- Chunked fetching via `chunk_days` parameter.
+- Four runnable example scripts.
+- Minitest test suite with recorded fixtures (no network access).

07 Ruby Exchange Gems/SMO-SEPA-KiWIS/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

07 Ruby Exchange Gems/SMO-SEPA-KiWIS/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

07 Ruby Exchange Gems/SMO-SEPA-KiWIS/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Madrid Ontiveros
+
+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.

07 Ruby Exchange Gems/SMO-SEPA-KiWIS/README.md

@@ -0,0 +1,175 @@
+# smo_sepa_kiwis
+
+A pure-Ruby client for the [SEPA Time Series KiWIS API](https://timeseriesdoc.sepa.org.uk/api-documentation/).
+Fetch rainfall stations, 15-minute timeseries metadata, and timeseries values.
+Export everything to CSV.
+
+Built specifically for use inside InfoWorks ICM 2027's embedded Ruby interpreter,
+where no `gem install` step is possible.
+
+## Support
+
+This gem is free and open source. If it saves you time on a hydraulic
+modelling project, you can support development here:
+
+<p align="center">
+  <a href="https://buymeacoffee.com/smadrid">
+    <img src="https://github.com/Sebasmadridmx/SMO-WGS84-TO-BNG/raw/main/temp_png/buymecoffeeqr.png" width="180" alt="Buy Me a Coffee QR code">
+  </a>
+  <br>
+  <a href="https://buymeacoffee.com/smadrid">buymeacoffee.com/smadrid</a>
+</p>
+
+## Why this gem
+
+Hydraulic modellers working in InfoWorks ICM often need rainfall observations
+from SEPA gauges to drive 1D-2D simulations or validate model performance.
+Pulling that data manually through the SEPA web portal does not scale beyond
+a handful of stations.
+
+This gem makes the SEPA KiWIS API directly callable from any Ruby environment,
+including ICM's embedded interpreter. It uses stdlib only (`net/http`, `uri`,
+`json`, `csv`, `date`, `time`), has no native extensions, and no Bundler
+runtime dependencies.
+
+## Installation
+
+```sh
+gem install smo_sepa_kiwis
+```
+
+```ruby
+require "smo_sepa_kiwis"
+```
+
+## Quick start
+
+```ruby
+require "smo_sepa_kiwis"
+
+client = SmoSepaKiwis::Client.new
+# Optional kwargs: base_url:, timeout: (default 60), user_agent:
+```
+
+### 1. List all rainfall stations
+
+```ruby
+stations = client.rainfall_stations
+# => Array<SmoSepaKiwis::Station>
+# Station fields: no, name, lat, lon, catchment, river
+```
+
+### 2. Find 15-minute timeseries for a specific station
+
+```ruby
+series = client.rainfall_15min_timeseries(station_no: "14964")
+# => Array<SmoSepaKiwis::Timeseries>
+# Timeseries fields: ts_id, ts_path, ts_name, station_no, coverage_from, coverage_to
+```
+
+### 3. Network-wide inventory in one call
+
+```ruby
+inventory = client.rainfall_15min_inventory
+# => Array<Hash> with keys:
+#    :station_no, :station_name, :lat, :lon, :catchment, :river,
+#    :ts_id, :ts_path, :coverage_from, :coverage_to
+```
+
+### 4. Download timeseries values
+
+```ruby
+values = client.timeseries_values(
+  ts_id: 55570010,
+  from:  "2021-10-22",
+  to:    "2021-10-25"
+)
+# => Array<SmoSepaKiwis::Value>
+# Value fields: timestamp (Time UTC), value (Float or nil), quality_code (Integer or nil)
+```
+
+`from` and `to` accept `String`, `Date`, `Time`, or `DateTime`.
+
+For long date ranges, use `chunk_days` to split the request into smaller
+windows and avoid server timeouts:
+
+```ruby
+values = client.timeseries_values(
+  ts_id:      55570010,
+  from:       "2020-01-01",
+  to:         "2021-01-01",
+  chunk_days: 30
+)
+```
+
+### 5. Export the full network inventory to CSV
+
+```ruby
+client.rainfall_15min_inventory_to_csv("inventory.csv")
+```
+
+### 6. Export timeseries values to CSV
+
+```ruby
+client.timeseries_values_to_csv(
+  ts_id: 55570010,
+  from:  "2021-10-22",
+  to:    "2021-10-25",
+  path:  "rainfall.csv"
+)
+```
+
+## Data fidelity
+
+This gem returns SEPA fields verbatim. String fields that are blank in the
+API response are set to `nil`. Numeric fields (`lat`, `lon`, `ts_id`) are
+coerced from the string representation SEPA provides. Timestamps are parsed
+as ISO 8601 and converted to UTC. No values are derived, interpolated, or
+synthesised.
+
+If you need British National Grid coordinates, the companion gem
+[`smo_wgs84_to_bng`](https://github.com/Sebasmadridmx) converts WGS84
+lat/lon to BNG easting/northing.
+
+## Examples
+
+The `examples/` directory contains runnable scripts:
+
+- `01_list_rainfall_stations.rb`: fetch all rainfall stations and save to CSV
+- `02_find_15min_timeseries.rb`: list 15-min series for a given station
+- `03_download_rainfall_event.rb`: download a storm event window
+- `04_bulk_export_csv.rb`: full inventory plus the last 7 days of values for every station
+
+Run any of them with:
+
+```sh
+ruby -Ilib examples/01_list_rainfall_stations.rb
+```
+
+## Compatibility
+
+- Ruby 3.2 and above
+- Tested with InfoWorks ICM 2027 embedded Ruby (3.4.6)
+- No external runtime dependencies
+
+## Author
+
+Sebastian Madrid Ontiveros, Senior Hydraulic Modeller (Edinburgh, UK).
+GitHub: [Sebasmadridmx](https://github.com/Sebasmadridmx)
+
+## Support this work
+
+If this gem saves you time on a hydraulic modelling project, consider
+buying me a coffee:
+
+<p align="center">
+  <a href="https://buymeacoffee.com/smadrid">
+    <img src="https://github.com/Sebasmadridmx/SMO-WGS84-TO-BNG/raw/main/temp_png/buymecoffeeqr.png" width="140" alt="Buy Me a Coffee QR code">
+  </a>
+  <br>
+  <a href="https://buymeacoffee.com/smadrid">buymeacoffee.com/smadrid</a>
+</p>
+
+## License
+
+MIT. Copyright (c) 2026 Sebastian Madrid Ontiveros.

07 Ruby Exchange Gems/SMO-SEPA-KiWIS/Rakefile

@@ -0,0 +1,9 @@
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "lib" << "test"
+  t.pattern = "test/test_*.rb"
+  t.verbose = true
+end
+
+task default: :test

07 Ruby Exchange Gems/SMO-SEPA-KiWIS/examples/01_list_rainfall_stations.rb

@@ -0,0 +1,12 @@
+require_relative "../lib/smo_sepa_kiwis"
+
+client   = SmoSepaKiwis::Client.new
+stations = client.rainfall_stations
+
+puts "Total stations: #{stations.size}"
+puts
+puts "%-10s %-30s %10s %10s" % ["No", "Name", "Lat", "Lon"]
+puts "-" * 64
+stations.each do |s|
+  puts "%-10s %-30s %10s %10s" % [s.no.to_s, s.name.to_s, s.lat.to_s, s.lon.to_s]
+end