feat!: rebuild the client on API specification 2.26.1

The 0.3.x line was generated in 2024 and has drifted well past usefulness: it
misses every operation the API has shipped since, including OMR, and it offers
nothing above the raw generated surface. This replaces it with a generated
client that is reproducible from this repository alone, plus the ergonomic
layer the README has always claimed.

Regenerated with openapi-generator 7.24.0 (ruby, faraday) against API
specification 2.26.1: 123 operations, 196 models, 23 scopes.

Four defects that no check in this repository would have caught, all found by
installing the gem and making real requests:

  * The gemspec declared typhoeus while tools/openapi-config.json selects the
    faraday library. `gem install flat_api` pulled a dependency the code never
    loads, and did not pull the ones it does. Now declares faraday,
    faraday-multipart and marcel.

  * The gem could not be loaded at all. The 200 response of
    createLtiConfiguration was an inline allOf over LtiConfiguration, which is
    a oneOf. This generator emits a oneOf as a module and an allOf as a
    subclass, so the output read `class CreateLtiConfiguration200Response <
    LtiConfiguration`, and a Ruby class cannot inherit a module. Fixed in the
    specification (BE-1213), not patched here.

  * The typed errors were dead code. errors.rb defined the hierarchy, and
    api_client.rb went on raising the generated ApiError, so nothing could ever
    rescue FlatNotFoundError. The raise site is rewired now.

  * None of errors.rb, retry.rb, pagination.rb or oauth.rb was required from
    lib/flat_api.rb, so `require 'flat_api'` gave you the generated client and
    nothing built on top of it. The retry policy, the pagination helper and the
    OAuth refresh were all unreachable. 95_requires.py wires them, errors
    first, because api_client.rb raises from it.

Also:

  * required_ruby_version moves from 3.0 to 3.3, matching the runtimes upstream
    still supports and the matrix in .sdkgen.yaml.
  * The gemspec ships LICENSE, README.md and CHANGELOG.md, and drops a
    test_files list pointing at a directory that does not exist.
  * Removes .gitlab-ci.yml. It is a leftover of an old generation: this
    repository has no GitLab mirror, the file pins Ruby 3.0 and 3.1, which the
    gemspec now refuses, and it runs rspec against a spec directory that is not
    there.
  * tools/smoke.rb drives the shared scenarios against the real API: score
    lifecycle, a paginated traversal and both typed errors, cleaning up what it
    creates. Nothing metered.
  * Stops tracking .DS_Store.
  * Removes the test harness that was never wired up: an rspec development
    dependency and a .rspec requiring a spec_helper that does not exist, a
    Rakefile task over a spec directory that does not exist, pry-byebug, and a
    rubocop pinned to 0.66.0 from 2019 with a config targeting Ruby 2.4 and
    excluding Rails paths. Nothing ran any of it, and rubocop at that pin
    cannot parse the Ruby this gem now requires. CI builds the gem and loads
    every file, which is the same shape as the Python client's.

A second round, after a review pointed at four more of exactly the same kind.
Each was written, documented in the README and never reached by a request:

  * FlatApi::FlatClient did not exist. The first code sample in the README and
    in QUICKSTART raised NameError, and so did the pagination example below it.
    30_client.py writes it: it holds one ApiClient, exposes each generated API
    by a short name, and paginates without the caller seeing a cursor. It builds
    its own Configuration rather than mutating Configuration.default, so two
    clients with different tokens do not overwrite each other.

  * Pagination sent the cursor as :next. The generator renames the parameter to
    :_next, because next is a Ruby keyword, and maps it back to the next query
    parameter itself. Every iteration therefore refetched page one; the loop
    guard saw a cursor it had already used and stopped. Traversals returned the
    first page and looked like they had reached the end.

  * RetryPolicy was never called. call_api is now a wrapper around the renamed
    call_api_once, and Configuration carries a retry_policy to tune or disable
    it. Wrapping the one request path rather than the 127 generated methods.

  * TokenManager#access_token returned the token whether or not it had expired,
    which made Tokens#expired? dead code. It now refreshes, re-checking inside
    the lock so that two threads arriving together spend one round trip rather
    than two, and so a provider that rotates refresh tokens does not have the
    second call invalidate what the first stored.

The smoke suite passed through all four, so it changed too:

  * It goes through FlatClient, the entry point the documentation points at.
  * The pagination check creates three collections and traverses with limit=1,
    so it cannot pass without following the cursor. The previous version asked
    for ten items on an account holding fewer, never requested a second page,
    and proved nothing.
  * Two checks that need no network cover the retry wiring and the token
    refresh, since a build cannot tell a module that runs from one that does
    not.
  * scenarios.yaml listed two scenarios no runner executed. It now describes
    what actually runs.

Author: gierschv

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+# Build and load checks. Everything that needs a credential runs elsewhere and reports
+# back as a commit status, so no secret is reachable from this workflow.
+
+on:
+  pull_request:
+  push:
+    branches: [master, main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: build (ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.3', '3.4']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Load every file
+        run: bundle exec ruby -Ilib -e "require 'flat_api'; puts FlatApi::VERSION"

.github/workflows/gem-push.yml

@@ -0,0 +1,33 @@
+name: Release
+
+# Publishing is triggered by a version tag and nothing else (FR-019a).
+
+on:
+  push:
+    tags: ['[0-9]+.[0-9]+.[0-9]+']
+
+permissions:
+  contents: read
+  id-token: write # OIDC for RubyGems trusted publishing (FR-021a)
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: rubygems
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: The tag must match the packaged version
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          PKG="$(ruby -Ilib -e "require 'flat_api/version'; print FlatApi::VERSION")"
+          [ "$TAG" = "$PKG" ] || { echo "tag $TAG != VERSION $PKG"; exit 1; }
+
+      - run: gem build flat_api.gemspec
+
+      # No API key: RubyGems trusts this repository and workflow by OIDC.
+      - uses: rubygems/release-gem@v1

.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: Tag on merge
+
+# Merging is what creates the version tag, and the tag is what publishes (FR-007f, FR-019a).
+# A breaking release waits for a human to merge, which is how the FR-019 approval is expressed.
+
+on:
+  push:
+    branches: [master, main]
+
+permissions:
+  contents: write
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    steps:
+      # SDK_RELEASE_TOKEN, not the automatic GITHUB_TOKEN. GitHub does not start a workflow run for
+      # an event created with GITHUB_TOKEN, so a tag pushed with it would never trigger release.yml
+      # and nothing would ever publish. That failure is silent: the tag appears, the release
+      # workflow simply never runs. Needs contents:write on this repository.
+      # Checked before checkout. An empty token there surfaces as a bare "Input required and not
+      # supplied: token", which says nothing about which secret is missing or why it matters.
+      - name: SDK_RELEASE_TOKEN must be set
+        run: |
+          test -n "${{ secrets.SDK_RELEASE_TOKEN }}" || {
+            echo "SDK_RELEASE_TOKEN is not set on this repository."
+            echo
+            echo "The tag has to be pushed with it rather than the automatic GITHUB_TOKEN, because"
+            echo "GitHub does not start a workflow run for an event created with that token. The"
+            echo "tag would appear and release.yml would never fire, publishing nothing."
+            exit 1
+          }
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.SDK_RELEASE_TOKEN }}
+      - name: Tag the version if it is new
+        run: |
+          VERSION="$(cat VERSION)"
+          if git rev-parse "$VERSION" >/dev/null 2>&1; then
+            echo "Tag $VERSION already exists, nothing to do."
+            exit 0
+          fi
+          git config user.name  "Flat SDK bot"
+          git config user.email "developers@flat.io"
+          git tag -a "$VERSION" -m "Release $VERSION"
+          git push origin "$VERSION"

.github/workflows/ruby.yml

@@ -37,3 +37,9 @@ build/
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
+
+# build artifacts
+*.gem
+.sdkgen-scratch/
+.openapi-spec.yaml
+.DS_Store