lingara 0.1.0.pre.alpha.6

data/lib/lingara/response.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lingara
+  # A JSON operation's result: #value is the generated response model (a
+  # Hash for getOpenApiDocument) and #served_version the Lingara-Version
+  # echo, or nil when the server sent none.
+  Response = Struct.new(:value, :served_version)
+
+  # What a stream's block form returns once its terminal event is handled.
+  StreamResult = Struct.new(:served_version)
+
+  # Every call into generated decoding runs here, under one rescue: the
+  # generated models' writers raise on a missing required field, an
+  # out-of-range value or an unknown enum value, and that must stay inside
+  # K3 (D2, the decode rule). Only a pure, non-blocking step is wrapped.
+  module Decoding
+    module_function
+
+    # A JSON response body as +model+ (a generated class name, or nil for a
+    # plain Hash).
+    def response(model, body)
+      value = JSON.parse(body)
+      return value if model.nil? && value.is_a?(Hash)
+      raise TransportError.new(:malformed_response, "the response body is not a JSON object") unless value.is_a?(Hash)
+      Lingara.const_get(model).build_from_hash(value)
+    rescue Lingara::Error
+      raise
+    rescue
+      raise TransportError.new(:malformed_response, "the response body does not decode")
+    end
+
+    # One known event as its generated branch. A +data+ that is not a JSON
+    # object, or that the branch refuses, is :malformed_event.
+    def event(branch, name, data)
+      parsed = JSON.parse(data)
+      raise TransportError.new(:malformed_event, "#{name}: data is not a JSON object") unless parsed.is_a?(Hash)
+      branch.build_from_hash({"event" => name, "data" => parsed})
+    rescue Lingara::Error
+      raise
+    rescue
+      raise TransportError.new(:malformed_event, "#{name}: data does not decode")
+    end
+  end
+end

data/lib/lingara/retry.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Lingara
+  # K4's Retry-After loop around one HTTP request, and K1's one 401 retry
+  # around a /v1 call (CONTRACT.md K1, K4).
+  #
+  # Each HTTP request has its own budget of max_attempts. The token exchange
+  # is one request and the /v1 request another, and the 401 retry sends the
+  # /v1 request again with a fresh budget. Every decision is made on the
+  # status line and headers alone, before any body byte reaches the caller.
+  class RetryPolicy
+    # A delta above this is far past any cap; clamping keeps it an Integer
+    # of sane size.
+    MAX_DELTA = 2**32
+
+    attr_reader :max_attempts, :retry_after_cap, :clock, :sleeper
+
+    def initialize(max_attempts:, retry_after_cap:, clock:, sleeper:)
+      raise ArgumentError, "max_attempts: must be at least 1" unless max_attempts.is_a?(Integer) && max_attempts >= 1
+      raise ArgumentError, "retry_after_cap: must be a non-negative number" unless retry_after_cap.is_a?(Numeric) && retry_after_cap >= 0
+      @max_attempts = max_attempts
+      @retry_after_cap = retry_after_cap
+      @clock = clock
+      @sleeper = sleeper
+    end
+
+    def now
+      @clock.call
+    end
+
+    # Retry-After as whole seconds: delta-seconds, or an HTTP-date read
+    # against +now+ (max(0, date − now), rounded up). Absent or unreadable is
+    # nil.
+    def self.parse_retry_after(value, now)
+      value = value.to_s.strip
+      return nil if value.empty?
+      return [value.to_i, MAX_DELTA].min if value.match?(/\A\d+\z/)
+      at = Time.httpdate(value)
+      [(at - now).ceil, 0].max
+    rescue ArgumentError
+      nil
+    end
+
+    # How long to wait before trying again, or nil to hand the response back.
+    def wait_for(response, tries)
+      return nil unless [429, 503].include?(response.code.to_i)
+      return nil if tries >= @max_attempts
+      wait = RetryPolicy.parse_retry_after(response["Retry-After"], now)
+      return nil if wait.nil? || wait > @retry_after_cap
+      wait
+    end
+
+    # Runs +attempt+ (which returns an Attempt) until it answers something
+    # other than a retryable 429 or 503, or the attempts run out, and returns
+    # the last Attempt. A TransportError is never retried: it propagates.
+    def run
+      tries = 1
+      loop do
+        attempt = yield
+        wait = attempt.response && wait_for(attempt.response, tries)
+        return attempt unless wait
+        @sleeper.call(wait)
+        tries += 1
+      end
+    end
+
+    # K1's one 401 retry: send with a token; on a 401, forget that token
+    # (only if it is still the cached one), get another and send once more.
+    # A second 401 is handed back for the caller to map.
+    def self.with_token_retry(tokens)
+      first = tokens.token
+      attempt = yield first
+      return attempt unless attempt.status == 401
+      tokens.invalidate(first)
+      yield tokens.token
+    end
+  end
+
+  # One HTTP attempt's result: either a +value+ the success handler produced,
+  # or a refused +response+ with the +body+ read from it.
+  Attempt = Struct.new(:response, :body, :value, :done) do
+    def status
+      response&.code&.to_i
+    end
+  end
+end

data/lib/lingara/sse_decoder.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Lingara
+  # K5's frame parser (CONTRACT.md K5, Parsing): pure, with no I/O. It
+  # buffers bytes, splits lines at \r\n, \n or \r (holding a trailing \r
+  # until the next byte says whether a \n follows), and decodes UTF-8 only per
+  # complete line, so a character split across chunks is never decoded half.
+  # The frames it returns are the same however the bytes were chunked.
+  class SSEDecoder
+    # One dispatched frame: its event name (`message` when none was sent)
+    # and its data lines joined by \n.
+    Frame = Struct.new(:event, :data)
+
+    CR = "\r".b.freeze
+    LF = "\n".b.freeze
+
+    def initialize
+      @buffer = +"".b
+      @event = nil
+      @data = nil
+    end
+
+    # Feeds bytes and returns every frame they complete.
+    def feed(bytes)
+      @buffer << bytes.b
+      frames = []
+      while (line = next_line)
+        frame = take_line(line)
+        frames << frame if frame
+      end
+      frames
+    end
+
+    # The end of the stream: a partial line is dropped, as is any frame with
+    # no blank line after it. Nothing further is dispatched.
+    def finish
+      @buffer.clear
+      @event = nil
+      @data = nil
+      []
+    end
+
+    private
+
+    # The next complete line, its terminator removed, or nil. A \r at the
+    # very end of the buffer is held until the next byte arrives.
+    def next_line
+      index = @buffer.index(/[\r\n]/n)
+      return nil unless index
+      if @buffer.getbyte(index) == 13
+        return nil if index == @buffer.bytesize - 1
+        length = (@buffer.getbyte(index + 1) == 10) ? 2 : 1
+      else
+        length = 1
+      end
+      line = @buffer.byteslice(0, index)
+      @buffer = @buffer.byteslice(index + length, @buffer.bytesize - index - length)
+      line.force_encoding(Encoding::UTF_8).scrub
+    end
+
+    def take_line(line)
+      return dispatch if line.empty?
+      return nil if line.start_with?(":")
+      field, value = line.split(":", 2)
+      value = value&.delete_prefix(" ") || ""
+      case field
+      when "event" then @event = value
+      when "data" then @data = @data ? "#{@data}\n#{value}" : value
+      end
+      nil
+    end
+
+    def dispatch
+      frame = @data && Frame.new(@event || "message", @data)
+      @event = nil
+      @data = nil
+      frame
+    end
+  end
+end

data/lib/lingara/streams.rb

@@ -0,0 +1,104 @@
+# Generated by ruby/codegen/generate.rb from the generator view. DO NOT EDIT.
+
+module Lingara
+  # One event of createLessonPlan's stream: `case event in CreateLessonPlanEvent` matches
+  # any of its branches. The error branch, and a Done-bodied one, are never
+  # yielded.
+  module CreateLessonPlanEvent
+    BRANCHES = {
+      "started" => CreateLessonPlanEventStarted,
+      "phase" => CreateLessonPlanEventPhase,
+      "result" => CreateLessonPlanEventResult,
+      "error" => CreateLessonPlanEventError
+    }.freeze
+
+    def self.===(other)
+      BRANCHES.value?(other.class)
+    end
+
+    # The branch for a known event name, decoded from its `data` JSON text,
+    # or nil for an unknown name. A known event whose data is not a JSON
+    # object, or that its branch refuses, raises TransportError
+    # :malformed_event.
+    def self.decode(name, data)
+      branch = BRANCHES[name]
+      branch && Lingara::Decoding.event(branch, name, data)
+    end
+  end
+
+  # One event of generateVocabulary's stream: `case event in GenerateVocabularyEvent` matches
+  # any of its branches. The error branch, and a Done-bodied one, are never
+  # yielded.
+  module GenerateVocabularyEvent
+    BRANCHES = {
+      "started" => GenerateVocabularyEventStarted,
+      "item" => GenerateVocabularyEventItem,
+      "done" => GenerateVocabularyEventDone,
+      "error" => GenerateVocabularyEventError
+    }.freeze
+
+    def self.===(other)
+      BRANCHES.value?(other.class)
+    end
+
+    # The branch for a known event name, decoded from its `data` JSON text,
+    # or nil for an unknown name. A known event whose data is not a JSON
+    # object, or that its branch refuses, raises TransportError
+    # :malformed_event.
+    def self.decode(name, data)
+      branch = BRANCHES[name]
+      branch && Lingara::Decoding.event(branch, name, data)
+    end
+  end
+
+  # One event of sendTutorMessage's stream: `case event in SendTutorMessageEvent` matches
+  # any of its branches. The error branch, and a Done-bodied one, are never
+  # yielded.
+  module SendTutorMessageEvent
+    BRANCHES = {
+      "delta" => SendTutorMessageEventDelta,
+      "notice" => SendTutorMessageEventNotice,
+      "done" => SendTutorMessageEventDone,
+      "error" => SendTutorMessageEventError
+    }.freeze
+
+    def self.===(other)
+      BRANCHES.value?(other.class)
+    end
+
+    # The branch for a known event name, decoded from its `data` JSON text,
+    # or nil for an unknown name. A known event whose data is not a JSON
+    # object, or that its branch refuses, raises TransportError
+    # :malformed_event.
+    def self.decode(name, data)
+      branch = BRANCHES[name]
+      branch && Lingara::Decoding.event(branch, name, data)
+    end
+  end
+
+  # One event of streamLessonPlan's stream: `case event in StreamLessonPlanEvent` matches
+  # any of its branches. The error branch, and a Done-bodied one, are never
+  # yielded.
+  module StreamLessonPlanEvent
+    BRANCHES = {
+      "started" => StreamLessonPlanEventStarted,
+      "phase" => StreamLessonPlanEventPhase,
+      "result" => StreamLessonPlanEventResult,
+      "pending" => StreamLessonPlanEventPending,
+      "error" => StreamLessonPlanEventError
+    }.freeze
+
+    def self.===(other)
+      BRANCHES.value?(other.class)
+    end
+
+    # The branch for a known event name, decoded from its `data` JSON text,
+    # or nil for an unknown name. A known event whose data is not a JSON
+    # object, or that its branch refuses, raises TransportError
+    # :malformed_event.
+    def self.decode(name, data)
+      branch = BRANCHES[name]
+      branch && Lingara::Decoding.event(branch, name, data)
+    end
+  end
+end

data/lib/lingara/transport.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module Lingara
+  # Raised into the token flight's own thread when one exchange attempt
+  # outlives token_request_timeout: (D3). Being a Timeout::Error, it is one
+  # Net::HTTP's own cleanup already handles.
+  class TokenAttemptTimeout < Timeout::Error; end
+
+  # One HTTP request per Net::HTTP.start, so leaving it by any path closes the
+  # socket, and the mapping of what Net::HTTP raises onto TransportError kinds
+  # (D3, D4). Only the classes named here are rescued: a caller's interrupt,
+  # and an exception raised by a caller's own block, pass through untouched.
+  class Transport
+    # The settings the library owns, whatever net_http_options: says:
+    # max_retries on every request, and read_timeout on a stream, where it
+    # is the idle timeout (#request's read_timeout:). A JSON call keeps a
+    # caller's read_timeout, or Net::HTTP's own 60 s.
+    OWNED = %i[max_retries].freeze
+
+    # The classes a request may fail with, in D4's order.
+    TLS = [OpenSSL::SSL::SSLError].freeze
+    CONNECT = [Net::OpenTimeout, SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH].freeze
+    TIMEOUT = [Net::ReadTimeout, Net::WriteTimeout, TokenAttemptTimeout].freeze
+    OTHER = [SystemCallError, IOError, Net::HTTPBadResponse].freeze
+    NAMED = (TLS + CONNECT + TIMEOUT + OTHER).freeze
+
+    # What one request has got as far as, for the kind mapping: whether its
+    # status line and headers are in, whether it is an open event stream,
+    # and whether control is inside a caller's block.
+    class Phase
+      attr_accessor :headers_seen, :event_stream, :in_caller
+      attr_reader :tag
+
+      def initialize(tag)
+        @tag = tag
+        @headers_seen = false
+        @event_stream = false
+        @in_caller = false
+      end
+
+      # Leaves the request at once, closing the socket unread: Net::HTTP.start's
+      # ensure runs and nothing drains the body (D3, the terminal event).
+      def leave(value = nil)
+        throw @tag, value
+      end
+
+      # Runs a caller's block; an exception from it is the caller's own.
+      def in_caller_block
+        @in_caller = true
+        result = yield
+        @in_caller = false
+        result
+      end
+    end
+
+    def initialize(net_http_options:)
+      @options = net_http_options.transform_keys(&:to_sym).except(*OWNED)
+    end
+
+    # Sends one request and yields the response and its Phase once the headers
+    # are in. Returns the block's value, or whatever Phase#leave was given.
+    # +secrets+ are scrubbed from any error's cause; +on_start+ receives the
+    # started Net::HTTP (EventStream#close finishes it).
+    def request(method, url, headers, body: nil, read_timeout: nil, secrets: [], on_start: nil)
+      uri = URI(url)
+      phase = Phase.new(Object.new)
+      catch(phase.tag) do
+        Net::HTTP.start(uri.host, uri.port, **start_options(uri, read_timeout)) do |http|
+          on_start&.call(http)
+          # Net::HTTP#request returns the response, not the block's value.
+          value = nil
+          http.request(build(method, uri, headers, body)) do |response|
+            phase.headers_seen = true
+            value = yield response, phase
+          end
+          value
+        end
+      end
+    rescue *NAMED => e
+      raise if phase.in_caller
+      raise_transport(Transport.kind(e, phase), e, secrets)
+    end
+
+    # D4's order; the first match wins.
+    def self.kind(error, phase)
+      case error
+      when *TLS then (phase.event_stream && eof_like?(error)) ? :stream_ended_early : :tls
+      when *CONNECT then :connect
+      when *TIMEOUT then :timeout
+      when Net::HTTPBadResponse then :malformed_response
+      else
+        if !phase.headers_seen then :connect
+        elsif phase.event_stream && error.is_a?(EOFError) then :stream_ended_early
+        else :reset
+        end
+      end
+    end
+
+    # OpenSSL 3 reports a peer that closes without close_notify as an
+    # SSLError rather than an EOF; on an open stream that is C2 D6's EOF.
+    def self.eof_like?(error)
+      error.message.include?("unexpected eof")
+    end
+
+    private
+
+    def start_options(uri, read_timeout)
+      options = @options.merge(use_ssl: uri.scheme == "https", max_retries: 0)
+      options[:read_timeout] = read_timeout if read_timeout
+      options
+    end
+
+    def build(method, uri, headers, body)
+      request = Net::HTTPGenericRequest.new(method, !body.nil?, method != "HEAD", uri, headers)
+      request.body = body if body
+      request
+    end
+
+    def raise_transport(kind, error, secrets)
+      text = error.message.to_s
+      if secrets.any? { |secret| secret && !secret.empty? && text.include?(secret) }
+        raise TransportError.new(kind), cause: ScrubbedCause.new
+      end
+      raise TransportError.new(kind, "#{error.class}: #{text}")
+    end
+  end
+end

data/lib/lingara/user_agent.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Lingara
+  # K6: `lingara-ruby/<VERSION> (ruby/<RUBY_VERSION>; <RUBY_PLATFORM>)`, the
+  # library's token first and a caller's suffix after one space. VERSION is
+  # the SemVer spelling, never GEM_VERSION, whose `.pre.` the contract's
+  # pattern refuses.
+  module UserAgent
+    # Visible ASCII with no `)`: CONTRACT.md K6's <runtime>.
+    RUNTIME = /\A[\x20-\x28\x2A-\x7E]+\z/
+
+    module_function
+
+    def build(suffix = nil, version: VERSION, runtime: default_runtime)
+      runtime = "ruby/unknown" unless runtime.match?(RUNTIME)
+      agent = "lingara-ruby/#{version} (#{runtime})"
+      (suffix.nil? || suffix.empty?) ? agent : "#{agent} #{suffix}"
+    end
+
+    def default_runtime
+      "ruby/#{RUBY_VERSION}; #{RUBY_PLATFORM}"
+    end
+  end
+end

data/lib/lingara/version.rb

@@ -0,0 +1,13 @@
+# Generated by ruby/codegen/generate.rb from the generator view. DO NOT EDIT.
+
+module Lingara
+  # This library's released version, SemVer, sent in every User-Agent (K6).
+  VERSION = "0.1.0-alpha.6"
+
+  # The same version in RubyGems' spelling, which the gemspec uses.
+  GEM_VERSION = "0.1.0.pre.alpha.6"
+
+  # The /v1 version this library's models were generated from. A response
+  # served under another version logs one warning per version id.
+  GENERATED_FOR_VERSION = "2026-09-glowing-hoatzin"
+end

data/lib/lingara.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# The Lingara API client (https://api.getlingara.com): the standard library
+# only. Lingara::Client is the entry point; conformance/CONTRACT.md is the
+# behaviour every official library keeps.
+
+require_relative "lingara/version"
+require_relative "lingara/errors"
+require_relative "lingara/access_token"
+require_relative "lingara/retry"
+require_relative "lingara/transport"
+require_relative "lingara/user_agent"
+require_relative "lingara/deprecation"
+require_relative "lingara/sse_decoder"
+require_relative "lingara/response"
+
+Dir[File.join(__dir__, "lingara/models/*.rb")].sort.each { |file| require file }
+
+require_relative "lingara/streams"
+require_relative "lingara/operations"
+require_relative "lingara/client_credentials"
+require_relative "lingara/event_stream"
+require_relative "lingara/client"

data/sig/lingara.rbs

@@ -0,0 +1,151 @@
+module Lingara
+  VERSION: String
+  GEM_VERSION: String
+  GENERATED_FOR_VERSION: String
+  OPERATIONS: Hash[String, Hash[Symbol, untyped]]
+
+  type seconds = Integer | Float
+  type event = untyped
+
+  interface _TokenSource
+    def token: () -> AccessToken
+    def invalidate: (AccessToken token) -> void
+  end
+
+  interface _Logger
+    def warn: (String message) -> untyped
+    def debug: (String message) -> untyped
+  end
+
+  class Client
+    DEFAULT_BASE_URL: String
+    DEFAULT_TOKEN_URL: String
+
+    attr_reader token_source: _TokenSource?
+
+    def initialize: (
+      ?client_id: String?,
+      ?client_secret: String?,
+      ?auth: (:basic | :post)?,
+      ?scopes: Array[String]?,
+      ?token_source: _TokenSource?,
+      ?base_url: String,
+      ?token_url: String,
+      ?version: String?,
+      ?on_deprecation: (^(DeprecationNotice) -> void)?,
+      ?logger: _Logger,
+      ?max_attempts: Integer,
+      ?retry_after_cap: seconds,
+      ?stream_idle_timeout: seconds,
+      ?token_request_timeout: seconds,
+      ?user_agent_suffix: String?,
+      ?clock: ^() -> Time,
+      ?sleeper: ^(seconds) -> void,
+      ?net_http_options: Hash[Symbol, untyped]
+    ) -> void
+
+    def generate_vocabulary: (**untyped body) { (event) -> void } -> StreamResult
+                           | (**untyped body) -> EventStream
+    def create_lesson_plan: (**untyped body) { (event) -> void } -> StreamResult
+                          | (**untyped body) -> EventStream
+    def get_lesson_plan: (String plan_id) -> Response
+    def stream_lesson_plan: (String plan_id) { (event) -> void } -> StreamResult
+                          | (String plan_id) -> EventStream
+    def send_tutor_message: (**untyped body) { (event) -> void } -> StreamResult
+                          | (**untyped body) -> EventStream
+    def get_usage: () -> Response
+    def get_open_api_document: () -> Response
+    def list_api_versions: () -> Response
+    def get_api_version: (String version_id) -> Response
+  end
+
+  class Response
+    attr_reader value: untyped
+    attr_reader served_version: String?
+  end
+
+  class StreamResult
+    attr_reader served_version: String?
+  end
+
+  class EventStream
+    include Enumerable[event]
+
+    attr_reader served_version: String?
+
+    def each: () { (event) -> void } -> self
+            | () -> Enumerator[event, self]
+    def next: () -> event
+    def close: () -> nil
+  end
+
+  class AccessToken
+    def initialize: (String raw) -> void
+    def expose_secret: () -> String
+  end
+
+  class ClientCredentials
+    attr_reader client_id: String
+
+    def token: () -> AccessToken
+    def invalidate: (AccessToken token) -> void
+    def expose_secret: () -> String
+  end
+
+  class DeprecationLink
+    attr_reader raw: String
+    attr_reader target: untyped
+  end
+
+  class DeprecationNotice
+    attr_reader version: String?
+    attr_reader deprecated_at: Time?
+    attr_reader sunset_at: Time?
+    attr_reader link: DeprecationLink?
+    attr_reader headers: Hash[String, String]
+  end
+
+  class DefaultLogger
+    def warn: (String message) -> void
+    def debug: (String message) -> void
+  end
+
+  class Error < StandardError
+  end
+
+  class ApiError < Error
+    attr_reader status: Integer
+    attr_reader code: String
+    attr_reader retry_after: Integer?
+    attr_reader plan_id: String?
+    attr_reader served_version: String?
+  end
+
+  class OAuthError < Error
+    attr_reader status: Integer
+    attr_reader error: String
+    attr_reader description: String?
+    attr_reader retry_after: Integer?
+  end
+
+  class MaintenanceError < Error
+    attr_reader body: String
+    attr_reader retry_after: Integer?
+  end
+
+  class TransportError < Error
+    KINDS: Array[Symbol]
+
+    attr_reader kind: :connect | :tls | :reset | :timeout | :stream_ended_early | :malformed_response | :malformed_event
+  end
+
+  class SSEDecoder
+    class Frame
+      attr_reader event: String
+      attr_reader data: String
+    end
+
+    def feed: (String bytes) -> Array[Frame]
+    def finish: () -> Array[Frame]
+  end
+end