lingara 0.1.0.pre.alpha.6 → 0.1.0.pre.alpha.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9900f36d73945227ac18de4de3520240ed8be150dc9db270802d55d5a858d60d
-  data.tar.gz: 84897db9f327ec33dc6823a11b2489a29e5da845f86f0c7be8ed2b2b87fdbbc4
+  metadata.gz: 2f07665061b17c5e8388d90fd529d4bda81a9b18b14f6deb8d5c529564a77343
+  data.tar.gz: 1588f9415feaf547ae947c9590c9c87e79afd5ff32400fac34868232e5b54fae
 SHA512:
-  metadata.gz: d831190d39cc8a6d840d913764c06ef40129999b2908237cfbb1f1c7529f93a894883d15925a55a0006d321153beecf78c03c075ee466bc4380ddfc93c984453
-  data.tar.gz: 683926e460ce43175de4fb365168726f61a0d145e0fc6f80dd2f482ca9171b624a633accd4934c0c8dd4b2cc0459a8f4663b181cfd8612c4b337514974d06228
+  metadata.gz: 934088a50dbcb89e78dcfc49ee42de87888266b4f84dbcde35eaf7f90c06068cf8dc005db6c1e1174ec86b6263f56c5684f7a58b6cb18e786a53d2ed998f2cdd
+  data.tar.gz: bb59e7307ae5f904409649db90970e66edd3546bea4cc9bcf43c16affdae0d3ff172f4a65ba4741c505f946969067b9164f6fe644470742449a9be3b786fc3da

data/README.md

@@ -40,10 +40,12 @@ usage = client.get_usage          # Lingara::Response
 p usage.value.allowance, usage.served_version
 ```
 
-Nine methods, each the `operationId` in snake_case: `generate_vocabulary`,
+Thirteen methods, each the `operationId` in snake_case: `generate_vocabulary`,
 `create_lesson_plan`, `get_lesson_plan`, `stream_lesson_plan`,
 `send_tutor_message`, `get_usage`, `get_open_api_document`,
-`list_api_versions` and `get_api_version`. A path parameter is a positional
+`get_async_api_document`, `list_api_versions`, `get_api_version`,
+`list_events`, `stream_events` and `send_event`, plus the two event helpers
+`events` and `tail_events` (see *Webhooks and events*). A path parameter is a positional
 `String` (`client.get_lesson_plan(plan_id)`); a request body is keyword
 arguments, and an unknown or missing keyword raises `ArgumentError` before any
 request is sent.
@@ -52,10 +54,10 @@ A JSON method returns a `Lingara::Response`: `#value` is the generated model
 (a `Hash` for `get_open_api_document`) and `#served_version` is the
 `Lingara-Version` the server answered under, or `nil`.
 
-`get_open_api_document`, `list_api_versions` and `get_api_version` need no
-token, so `Lingara::Client.new` with no credentials calls them. A client
-without credentials sends the other six without `Authorization`, and the
-server's `401` is the answer.
+`get_open_api_document`, `get_async_api_document`, `list_api_versions` and
+`get_api_version` need no token, so `Lingara::Client.new` with no credentials
+calls them. A client without credentials sends the other nine without
+`Authorization`, and the server's `401` is the answer.
 
 ## Streams
 
@@ -92,6 +94,69 @@ A stream fails with `Lingara::TransportError` (`kind: :timeout`) after
 while the library is waiting for your next event. Time you spend holding an
 event never counts.
 
+## Webhooks and events
+
+Every door carries one envelope (`id`, `type`, `created_at`, `api_version`,
+`subject`, `data`), and the library reads it into a `Lingara::Events::Event`:
+one `Data` class per type (`Lingara::Events::LessonPlanReady`, whose `data`
+is a `Lingara::LessonPlanReadyData`, and so on), or
+`Lingara::Events::UnknownEvent`, whose `data` is the raw `Hash`.
+`Lingara::Events.parse(json)` is the parser all three doors use.
+
+**Verify the raw body first.** `Lingara::Events::Webhook.new(secret)` (or an
+array of two secrets during a rotation) refuses anything but a
+`lgr_whsec_…` secret with `ArgumentError`. `#verify(body, headers)` takes the
+body exactly as received, a `String`, never a parsed object, and any `Hash`
+of headers, read case-insensitively and by Rack's `HTTP_WEBHOOK_ID`
+spelling, so a Rack `env` works as it is:
+
+```ruby
+webhook = Lingara::Events::Webhook.new(ENV.fetch("LINGARA_WEBHOOK_SECRET"))
+event = webhook.verify(request.body.read, request.env)   # Rack, Sinatra and Rails alike
+```
+
+It returns the event, or raises `Lingara::Events::VerificationError`, whose
+`#reason` is `:missing_header`, `:malformed_header`, `:timestamp_too_old`,
+`:timestamp_too_new` (300 s either way), `:no_matching_signature` or
+`:malformed_payload`. That error is deliberately **not** a `Lingara::Error`,
+so a `rescue Lingara::Error` around your API calls never swallows a forged
+webhook. `#verify_signature(body, headers)` checks the signature alone, for a
+signed body that is not an event.
+
+**Answer `2xx` fast and deduplicate by `event.id`**: delivery is at least once,
+and the verifier stores nothing. **Acknowledge an `UnknownEvent`** (and log
+it) rather than refusing it: the catalogue only grows, and a refused delivery
+is retried for about a day.
+
+**The feed.** `client.events(cursor:, start:, types:)` walks
+`list_events`' pages and yields each event, then stops at the horizon: it
+never waits. Its `#cursor` is where to resume, so keep it and pass it back
+later. Without a cursor, `start: :latest` (the default) means "from now" and
+`:oldest` means everything still kept. A cursor older than 30 days raises
+`Lingara::ApiError` with `code` `"cursor_expired"`: start again with no
+cursor, or with `start: :oldest`.
+
+**The tail.** `client.tail_events(cursor:, start:, types:)` yields live
+events and reconnects on its own from its `#cursor`, which is the same token
+as the feed's, so `tail_events(cursor: feed.cursor)` follows a catch-up with
+no gap. Leave the block to stop it. After `tail_max_failures:` (8)
+consecutive failed reconnects, 91 s of backoff by default, it raises the last
+failure; it never hides an outage forever. `stream_events` is the raw
+one-connection stream beneath it.
+
+**Sending.** `client.send_event(event, idempotency_key: nil)` takes a
+`Lingara::Events::InboundEvent`, such as
+`Lingara::Events::InboundEvent.world_context_changed(scene: "…", source_lang: "en", target_lang: "zh", level: 2, generate: true)`,
+and returns the `InboundEventAccepted`. Without a key the library makes one
+per call and repeats it on every retry. Supply your own when a game may
+resend after a crash, since a generated key dies with the call; a key reused
+for another event returns the **first** answer. Only
+`reaction.plan_status == "generating"` promises a `lesson_plan.ready` or
+`lesson_plan.failed`.
+
+Event `data` is rendered at your client's pinned version, and this library's
+models are those of `Lingara::GENERATED_FOR_VERSION`: pin your client to it.
+
 ## Errors
 
 Every failure is a `Lingara::Error`, one of four:
@@ -127,7 +192,8 @@ Every option is a keyword of `Lingara::Client.new`:
 | `stream_idle_timeout:`, `token_request_timeout:` | `120`, `30` (seconds) |
 | `user_agent_suffix:` | none; appended after the library's own product token |
 | `net_http_options:` | `{}`: forwarded to `Net::HTTP.start` (`ca_file:`, `open_timeout:` …). The library always sets `max_retries` to `0`, and a stream's `read_timeout` is the idle timeout |
-| `clock:`, `sleeper:` | `Time.now` and `sleep`. **Testing seams only**: the clock decides token freshness and HTTP-date waits, and the sleeper receives every `Retry-After` wait |
+| `tail_max_failures:` | `8`: consecutive failed reconnects before `tail_events` raises |
+| `clock:`, `sleeper:` | `Time.now` and `sleep`. **Testing seams only**: the clock decides token freshness and HTTP-date waits, and the sleeper receives every `Retry-After` wait and every tail backoff |
 
 The secret and every access token render as `[REDACTED]` in `inspect`,
 `to_s` and `pp`; `#expose_secret` is the one accessor that reads them. A

data/lib/lingara/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "securerandom"
 
 module Lingara
   # Calls the Lingara API. Every C2 knob is a keyword of Client.new (D3); a
@@ -12,7 +13,9 @@ module Lingara
   #
   # clock: and sleeper: are testing seams (C2 D9): the clock is read for
   # token freshness and HTTP-date Retry-After values, and the sleeper is
-  # handed every Retry-After wait in seconds.
+  # handed every Retry-After wait in seconds, and every tail backoff.
+  # tail_max_failures: bounds tail_events' consecutive failed reopens
+  # (K5a; ADR 30.9.26aa D7).
   class Client
     include Redacted
 
@@ -26,14 +29,18 @@ module Lingara
       base_url: DEFAULT_BASE_URL, token_url: DEFAULT_TOKEN_URL, version: nil, on_deprecation: nil,
       logger: DefaultLogger.new, max_attempts: 3, retry_after_cap: 60, stream_idle_timeout: 120,
       token_request_timeout: 30, user_agent_suffix: nil, clock: -> { Time.now },
-      sleeper: ->(seconds) { sleep(seconds) }, net_http_options: {})
+      sleeper: ->(seconds) { sleep(seconds) }, net_http_options: {}, tail_max_failures: 8)
       credentials = {client_id: client_id, client_secret: client_secret, auth: auth, scopes: scopes}
       check_options(credentials, token_source, version, stream_idle_timeout)
+      raise ArgumentError, "tail_max_failures: must be at least 1" unless tail_max_failures.is_a?(Integer) && tail_max_failures >= 1
+      @tail_max_failures = tail_max_failures
       @base_url = base_url.to_s.chomp("/")
       @version = version
       @idle = stream_idle_timeout
       @user_agent = UserAgent.build(user_agent_suffix)
       @policy = RetryPolicy.new(max_attempts: max_attempts, retry_after_cap: retry_after_cap, clock: clock, sleeper: sleeper)
+      # A tail open bypasses K4's attempt loop: its own count is the budget.
+      @tail_policy = RetryPolicy.new(max_attempts: 1, retry_after_cap: retry_after_cap, clock: clock, sleeper: sleeper)
       @transport = Transport.new(net_http_options: net_http_options)
       @versions = VersionObserver.new(hook: on_deprecation, logger: logger)
       @token_source = token_source || (client_id && ClientCredentials.new(
@@ -42,7 +49,7 @@ module Lingara
       ))
     end
 
-    # ── The nine operations, over operations.rb ───────────────────────────
+    # ── The thirteen operations, over operations.rb ───────────────────────
 
     # Streams a vocabulary list (scope vocab:generate).
     def generate_vocabulary(**body, &block)
@@ -91,6 +98,66 @@ module Lingara
       json("getApiVersion", [version_id])
     end
 
+    # The API's AsyncAPI document, the event catalogue, as a Hash. Needs no
+    # token.
+    def get_async_api_document
+      json("getAsyncApiDocument", [])
+    end
+
+    # ── Events (ADR 30.9.26aa D6–D8) ──────────────────────────────────────
+
+    # One page of events, an EventPage (scope events:read). +types+ is a
+    # list, sent comma-separated.
+    def list_events(cursor: nil, start: nil, types: nil, limit: nil)
+      json("listEvents", [], query: {cursor: cursor, start: start, types: types, limit: limit})
+    end
+
+    # The feed: an Events::Feed that walks pages from +cursor+ (or +start+,
+    # :latest or :oldest, without one) to the horizon and yields each
+    # Events::Event. With a block, iterates it and returns the feed, whose
+    # #cursor is where to resume.
+    def events(cursor: nil, start: nil, types: nil, &block)
+      operation = OPERATIONS.fetch("listEvents")
+      fetch = ->(query) { page(operation, url_for(operation, [], query)) }
+      feed = Events::Feed.new(fetch: fetch, cursor: cursor, start: start, types: types)
+      block ? feed.each(&block) : feed
+    end
+
+    # The event stream itself, one connection under K5 (scope events:read):
+    # it yields StreamEventsEventEvent and ends on done. tail_events is the
+    # helper that resumes.
+    def stream_events(cursor: nil, start: nil, types: nil, last_event_id: nil, &block)
+      headers = last_event_id ? {"Last-Event-ID" => last_event_id} : {}
+      stream("streamEvents", [], nil, query: {cursor: cursor, start: start, types: types}, headers: headers, &block)
+    end
+
+    # The tail (K5a): an Events::Tail that yields each Events::Event and
+    # reconnects from its #cursor after any ending, until
+    # tail_max_failures: consecutive failures. It never ends on its own:
+    # leave the block to stop it.
+    def tail_events(cursor: nil, start: nil, types: nil, &block)
+      operation = OPERATIONS.fetch("streamEvents")
+      # The first request's URL, repeated by every reopen: start only
+      # without a cursor, which travels as Last-Event-ID instead.
+      url = url_for(operation, [], {start: (start unless cursor), types: types})
+      open = lambda do |last_event_id, on_start, &consume|
+        headers = last_event_id ? {"Last-Event-ID" => last_event_id} : {}
+        pipeline(operation, url, nil, on_start: on_start, headers: headers, policy: @tail_policy, &consume)
+      end
+      tail = Events::Tail.new(open: open, cursor: cursor, max_failures: @tail_max_failures, policy: @policy)
+      block ? tail.each(&block) : tail
+    end
+
+    # Sends one Events::InboundEvent (scope events:write, and
+    # lesson_plans:write when it asks for generation) and returns the
+    # InboundEventAccepted. Every attempt carries one Idempotency-Key: the
+    # caller's, unchanged, or a UUIDv4 made once for this call (K4).
+    def send_event(event, idempotency_key: nil)
+      raise ArgumentError, "event must be a Lingara::Events::InboundEvent" unless event.is_a?(Events::InboundEvent)
+      key = idempotency_key || SecureRandom.uuid
+      json("sendEvent", [], body: JSON.generate(event.to_hash), headers: {"Idempotency-Key" => key})
+    end
+
     def to_s
       inspect
     end
@@ -112,22 +179,33 @@ module Lingara
       raise ArgumentError, "stream_idle_timeout: must be a positive number" unless idle.is_a?(Numeric) && idle.positive?
     end
 
-    def json(id, args)
+    # +body+ is JSON text already; +headers+ join every attempt's.
+    def json(id, args, query: nil, body: nil, headers: {})
       operation = OPERATIONS.fetch(id)
-      url = url_for(operation, args)
-      pipeline(operation, url, nil) do |response, _phase, observe|
+      url = url_for(operation, args, query)
+      pipeline(operation, url, body, headers: headers) do |response, _phase, observe|
         served = observe.call(response)
         Response.new(value: Decoding.response(operation[:response], response.body.to_s), served_version: served)
       end
     end
 
-    def stream(id, args, body, &block)
+    # One page of the feed as its raw Hash, so each item reaches
+    # Events.decode as the bytes the server sent (D6).
+    def page(operation, url)
+      pipeline(operation, url, nil) do |response, _phase, observe|
+        observe.call(response)
+        Decoding.page(response.body.to_s)
+      end
+    end
+
+    def stream(id, args, body, query: nil, headers: {}, &block)
       operation = OPERATIONS.fetch(id)
-      url = url_for(operation, args)
+      url = url_for(operation, args, query)
       # The request model's constructor refuses a bad keyword before any
       # request is sent: a programming error, like Client.new's.
       payload = body && JSON.generate(Lingara.const_get(operation[:request_body]).new(body).to_hash)
-      events = EventStream.new(pipeline: method(:pipeline), operation: operation, url: url, body: payload)
+      send = ->(*call, **options, &consume) { pipeline(*call, headers: headers, **options, &consume) }
+      events = EventStream.new(pipeline: send, operation: operation, url: url, body: payload)
       block ? events.run(&block) : events
     end
 
@@ -135,10 +213,11 @@ module Lingara
     # and the refusal mapping. Yields a 2xx response, its Transport::Phase and
     # the version observer, and returns what the block returns. A client with
     # no token source sends an operation that needs one without
-    # Authorization; the server's 401 is the answer.
-    def pipeline(operation, url, body, on_start: nil, &on_success)
+    # Authorization; the server's 401 is the answer. +policy+ is the tail's
+    # single-attempt one for a tail open (K5a).
+    def pipeline(operation, url, body, on_start: nil, headers: {}, policy: @policy, &on_success)
       send_all = lambda do |token|
-        @policy.run { attempt(operation, url, body, token, on_start, &on_success) }
+        policy.run { attempt(operation, url, body, [token, headers], on_start, &on_success) }
       end
       result = if @token_source && operation[:needs_token]
         RetryPolicy.with_token_retry(@token_source, &send_all)
@@ -149,9 +228,11 @@ module Lingara
       raise Refusal.error(:v1, result.response, result.body, @policy.now)
     end
 
-    def attempt(operation, url, body, token, on_start)
+    # +auth+ is the token and the call's own headers.
+    def attempt(operation, url, body, auth, on_start)
+      token, extra = auth
       observe = ->(response) { @versions.observe(response, url) }
-      result = @transport.request(operation[:method], url, headers(operation, body, token), body: body,
+      result = @transport.request(operation[:method], url, headers(operation, body, token).merge(extra), body: body,
         read_timeout: operation[:stream] && @idle, secrets: token ? [token.expose_secret] : [], on_start: on_start) do |response, phase|
         next Attempt.new(response: response, body: response.body.to_s) unless (200..299).cover?(response.code.to_i)
         Attempt.new(value: yield(response, phase, observe), done: true)
@@ -169,14 +250,21 @@ module Lingara
     end
 
     # The base URL and the route's path, each path parameter percent-encoded
-    # but for A–Z a–z 0–9 - . _ ~, as the other libraries do.
-    def url_for(operation, args)
+    # but for A–Z a–z 0–9 - . _ ~, as the other libraries do. +query+'s nil
+    # values are left out and a list is one comma-separated value
+    # (`explode: false`), encoded the same way.
+    def url_for(operation, args, query = nil)
       path = operation[:path].dup
       operation[:path_params].zip(args).each do |name, value|
         raise ArgumentError, "#{name} must be a non-empty String" unless value.is_a?(String) && !value.empty?
-        path.sub!("{#{name}}", value.b.gsub(/[^A-Za-z0-9\-._~]/n) { |c| format("%%%02X", c.ord) })
+        path.sub!("{#{name}}", encode(value))
       end
-      @base_url + path
+      pairs = (query || {}).reject { |_, value| value.nil? }.map { |name, value| "#{name}=#{encode(Array(value).join(","))}" }
+      pairs.empty? ? @base_url + path : "#{@base_url}#{path}?#{pairs.join("&")}"
+    end
+
+    def encode(value)
+      value.to_s.b.gsub(/[^A-Za-z0-9\-._~]/n) { |c| format("%%%02X", c.ord) }
     end
   end
 end

data/lib/lingara/errors.rb

@@ -135,6 +135,15 @@ module Lingara
       ApiError.new(status: status, code: code, message: message, retry_after: retry_after, served_version: served_version)
     end
 
+    # A stream's error event: ApiError with status 200. K5 raises it at
+    # once; the tail (K5a) only once its failures are spent.
+    def stream_error(data, served_version)
+      fields = parse_object(data)
+      text = ->(key, fallback) { fields[key].is_a?(String) ? fields[key] : fallback }
+      ApiError.new(status: 200, code: text.call("code", "stream_error"), message: text.call("message", "the stream reported an error"),
+        plan_id: text.call("plan_id", nil), served_version: served_version)
+    end
+
     def parse_object(body)
       value = JSON.parse(body.to_s)
       value.is_a?(Hash) ? value : {}

data/lib/lingara/event_stream.rb

@@ -103,7 +103,7 @@ module Lingara
       stream = @operation[:stream]
       return unless stream[:events].key?(frame.event)
       ending = stream[:ends][frame.event]
-      raise stream_error(frame.data) if ending == :raise
+      raise Refusal.stream_error(frame.data, @served_version) if ending == :raise
       return finish(phase, frame) if ending == :quiet
       event = Lingara.const_get(stream[:union]).decode(frame.event, frame.data)
       return if event.nil?
@@ -118,18 +118,5 @@ module Lingara
     rescue JSON::ParserError
       raise TransportError.new(:malformed_event, "#{frame.event}: data is not JSON")
     end
-
-    # An error event: ApiError with status 200, never yielded or retried.
-    def stream_error(data)
-      fields = begin
-        parsed = JSON.parse(data)
-        parsed.is_a?(Hash) ? parsed : {}
-      rescue JSON::ParserError
-        {}
-      end
-      text = ->(key, fallback) { fields[key].is_a?(String) ? fields[key] : fallback }
-      ApiError.new(status: 200, code: text.call("code", "stream_error"), message: text.call("message", "the stream reported an error"),
-        plan_id: text.call("plan_id", nil), served_version: @served_version)
-    end
   end
 end

data/lib/lingara/events/catalogue.rb

@@ -0,0 +1,107 @@
+# Generated by ruby/codegen/generate.rb from the generator view. DO NOT EDIT.
+
+require "json"
+
+module Lingara
+  module Events
+    # The envelope's fields, in the order every arm holds them.
+    ENVELOPE = %i[id type created_at api_version subject data].freeze
+
+    # One outbound event. Every arm, UnknownEvent included, is an Event, so
+    # `case event in Lingara::Events::Event` matches any of them.
+    module Event
+    end
+
+    # lesson_plan.ready: data is a Lingara::LessonPlanReadyData.
+    LessonPlanReady = Data.define(*ENVELOPE) { include Event }
+
+    # lesson_plan.failed: data is a Lingara::LessonPlanFailedData.
+    LessonPlanFailed = Data.define(*ENVELOPE) { include Event }
+
+    # usage.threshold_reached: data is a Lingara::UsageThresholdReachedData.
+    UsageThresholdReached = Data.define(*ENVELOPE) { include Event }
+
+    # webhook.test: data is a Hash.
+    WebhookTest = Data.define(*ENVELOPE) { include Event }
+
+    # app.installed: data is a Lingara::AppInstalledData.
+    AppInstalled = Data.define(*ENVELOPE) { include Event }
+
+    # app.uninstalled: data is a Lingara::AppUninstalledData.
+    AppUninstalled = Data.define(*ENVELOPE) { include Event }
+
+    # An event of a type this library does not know: data is the raw JSON
+    # object, as a Hash. The catalogue only grows, so acknowledge it.
+    UnknownEvent = Data.define(*ENVELOPE) { include Event }
+
+    module Event
+      # Each known type's arm and the name of its data model (nil: a Hash).
+      ARMS = {
+        "lesson_plan.ready" => [LessonPlanReady, "LessonPlanReadyData"].freeze,
+        "lesson_plan.failed" => [LessonPlanFailed, "LessonPlanFailedData"].freeze,
+        "usage.threshold_reached" => [UsageThresholdReached, "UsageThresholdReachedData"].freeze,
+        "webhook.test" => [WebhookTest, nil].freeze,
+        "app.installed" => [AppInstalled, "AppInstalledData"].freeze,
+        "app.uninstalled" => [AppUninstalled, "AppUninstalledData"].freeze
+      }.freeze
+    end
+
+    # An event a client sends with send_event: one constructor per inbound
+    # type, each taking its data model. It serialises as {type, data}; the
+    # server assigns the rest.
+    class InboundEvent
+      # Each inbound type's constructor.
+      CONSTRUCTORS = {
+        "world.context_changed" => :world_context_changed,
+        "world.practice_requested" => :world_practice_requested
+      }.freeze
+
+      attr_reader :type, :data
+
+      private_class_method :new
+
+      # world.context_changed, from a Lingara::WorldContextChanged or the Hash one is built from.
+      def self.world_context_changed(data)
+        new("world.context_changed", data.is_a?(Lingara::WorldContextChanged) ? data : Lingara::WorldContextChanged.new(data))
+      end
+
+      # world.practice_requested, from a Lingara::WorldPracticeRequested or the Hash one is built from.
+      def self.world_practice_requested(data)
+        new("world.practice_requested", data.is_a?(Lingara::WorldPracticeRequested) ? data : Lingara::WorldPracticeRequested.new(data))
+      end
+
+      def initialize(type, data)
+        @type = type
+        @data = data
+        freeze
+      end
+
+      def to_hash
+        {"type" => @type, "data" => @data.to_hash}
+      end
+    end
+
+    # The Event for one envelope's JSON text: its arm for a known type, or
+    # UnknownEvent. Text that is not an envelope, or a known type whose data
+    # its model refuses, raises TransportError :malformed_event.
+    def self.parse(json)
+      decode(JSON.parse(json))
+    rescue JSON::ParserError
+      raise Lingara::TransportError.new(:malformed_event, "an event is not JSON")
+    end
+
+    # The same, from an envelope already parsed into a Hash.
+    def self.decode(fields)
+      raise Lingara::TransportError.new(:malformed_event, "an event is not a JSON object") unless fields.is_a?(Hash)
+      envelope = Lingara::EventEnvelope.build_from_hash(fields)
+      arm, model = Event::ARMS.fetch(envelope.type, [UnknownEvent, nil])
+      data = model ? Lingara.const_get(model).build_from_hash(envelope.data) : envelope.data
+      arm.new(id: envelope.id, type: envelope.type, created_at: envelope.created_at, api_version: envelope.api_version,
+        subject: envelope.subject, data: data)
+    rescue Lingara::Error
+      raise
+    rescue
+      raise Lingara::TransportError.new(:malformed_event, "an event does not decode")
+    end
+  end
+end

data/lib/lingara/events/feed.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Lingara
+  module Events
+    # The feed helper (ADR 30.9.26aa D6; CONTRACT.md, The event helpers): it
+    # walks listEvents' pages and yields each item as an Event, parsed from
+    # the item's own JSON. #cursor is where to resume: after a page's last
+    # item, that page's next_cursor, which advances even on an empty page.
+    # It ends on a page with has_more false and never sleeps or polls; a
+    # later #each resumes from #cursor. A known type whose data does not
+    # decode raises TransportError :malformed_event, and every refusal its
+    # K3 error, 410 cursor_expired included.
+    class Feed
+      include Enumerable
+
+      attr_reader :cursor
+
+      # +fetch+ is the client's: it sends one listEvents request for a query
+      # and returns the page as a Hash.
+      def initialize(fetch:, cursor:, start:, types:)
+        @fetch = fetch
+        @cursor = cursor
+        @start = start
+        @types = types
+      end
+
+      # Yields each event to the horizon, then returns self. Without a
+      # block, an Enumerator.
+      def each
+        return enum_for(:each) unless block_given?
+        loop do
+          # start only without a cursor, the server's own precedence, so the
+          # helper never earns the 400 the pair draws.
+          page = @fetch.call(@cursor ? {cursor: @cursor, types: @types} : {start: @start, types: @types})
+          page["items"].each { |item| yield Events.decode(item) }
+          @cursor = page["next_cursor"]
+          break unless page["has_more"]
+        end
+        self
+      end
+
+      def inspect
+        "#<Lingara::Events::Feed cursor=#{@cursor.inspect}>"
+      end
+    end
+  end
+end

data/lib/lingara/events/tail.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Lingara
+  module Events
+    # The tail helper (CONTRACT.md K5a; ADR 30.9.26aa D7): streamEvents,
+    # reopened after every ending, so it never ends on its own. Leave the
+    # block (break, return or an exception) to stop it, at any point,
+    # including a reconnect sleep.
+    #
+    # #cursor is the id of the last frame that carried one, an event or a
+    # done, and every reopen sends it as Last-Event-ID. A done reopens at
+    # once. An error event, EOF and every TransportError are failures, the
+    # first open included: the sleeper is handed 1, 2, 4 … 30 s between
+    # them, and the max_failures-th consecutive one is raised. The count
+    # resets on a connection's first event or done frame, never on its 200.
+    # A tail open bypasses K4: a 429 or 503 is one failure whose Retry-After
+    # (within retry_after_cap) replaces that step's delay; 401 gets K1's one
+    # refresh; every other refusal, and a known type whose data does not
+    # decode, is raised at once.
+    class Tail
+      include Enumerable
+
+      # Why one connection ended, and the delay that replaces the backoff's.
+      Failure = Struct.new(:error, :delay)
+
+      MAX_DELAY = 30
+
+      attr_reader :cursor
+
+      # +open+ is the client's: it sends one streamEvents request, with
+      # Last-Event-ID when given one, and yields the 2xx response.
+      def initialize(open:, cursor:, max_failures:, policy:)
+        @open = open
+        @cursor = cursor
+        @max_failures = max_failures
+        @policy = policy
+        @failures = 0
+      end
+
+      # Yields each event until the block is left or the failures are spent.
+      # Without a block, an Enumerator.
+      def each(&block)
+        return enum_for(:each) unless block
+        @failures = 0
+        loop do
+          failure = connect(&block)
+          next if failure.nil?
+          @failures += 1
+          raise failure.error if @failures >= @max_failures
+          @policy.sleeper.call(failure.delay || [2**(@failures - 1), MAX_DELAY].min)
+        end
+      end
+
+      def inspect
+        "#<Lingara::Events::Tail cursor=#{@cursor.inspect}>"
+      end
+
+      private
+
+      # One connection: nil after a done, else its Failure.
+      def connect(&block)
+        @open.call(@cursor, nil) { |response, phase, observe| consume(response, phase, observe, &block) }
+      rescue TransportError => e
+        raise if e.kind == :malformed_event
+        Failure.new(e, nil)
+      rescue ApiError, MaintenanceError => e
+        busy(e)
+      end
+
+      # A 429 or 503 is a failure; any other refusal, and a Retry-After past
+      # the cap, is raised.
+      def busy(error)
+        status = error.is_a?(MaintenanceError) ? 503 : error.status
+        raise error unless [429, 503].include?(status)
+        raise error if error.retry_after && error.retry_after > @policy.retry_after_cap
+        Failure.new(error, error.retry_after)
+      end
+
+      def consume(response, phase, observe, &block)
+        unless Refusal.media_type(response) == "text/event-stream"
+          raise TransportError.new(:malformed_response, "a 200 stream answered #{Refusal.media_type(response).inspect}")
+        end
+        served = observe.call(response)
+        phase.event_stream = true
+        decoder = SSEDecoder.new
+        response.read_body do |chunk|
+          decoder.feed(chunk).each { |frame| handle(frame, phase, served, &block) }
+        end
+        Failure.new(TransportError.new(:stream_ended_early, "the tail closed before its ending event"), nil)
+      end
+
+      def handle(frame, phase, served, &block)
+        case frame.event
+        when "event"
+          event = Events.parse(frame.data)
+          advance(frame)
+          phase.in_caller_block { block.call(event) }
+        when "done"
+          advance(frame)
+          phase.leave(nil)
+        when "error"
+          phase.leave(Failure.new(Refusal.stream_error(frame.data, served), nil))
+        end
+      end
+
+      def advance(frame)
+        @failures = 0
+        @cursor = frame.id if frame.id && !frame.id.empty?
+      end
+    end
+  end
+end