flowspeech 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4aa33771a20fb9cb3f38ed4af5e46f47f6d884823a83c54e8d96c10fbe92f601
-  data.tar.gz: 3daec29ae0da53cf1931c3c4866847b717d068f443cc1ac056552b2ef661a616
+  metadata.gz: 77ffd1136c8cf4e44cffce0e60f46a55a785d3011f228eb894fa12674a5b0f3a
+  data.tar.gz: cbcf965a998720defa2dce9286b132b22cde88bf4e5c243bbae19e1e62579e27
 SHA512:
-  metadata.gz: 22522217c54774ae015a720d88a73a8f9fe18d8c465464d3fe08a2f1d65e7f77b8fae598567f6b6bd11efdf88561d2af317cb1b885c526f46c4ae2ea2d3d7284
-  data.tar.gz: b268e634167156062af46985c4af5df99aa2bf829152c84d2e8d86e41a84547f4a1b4d3df2a8463d637cffb2fff99240649c7ad08536983ff3a830a8f1df9121
+  metadata.gz: 6af7176948a2a08e459f9ccc6afdb9efe51f6384086b54fa0806c3333cac25217174b69a3c6a30a1f0e4e3421b7b003ddc7f53ac9a280c0a54acb1fd78426ac5
+  data.tar.gz: 514fa7b5655ffa6ae3a4f84d486437939988f3bfbac8526c7faa8921b5edee280c67b5d6278c93782c049255b4de262f7a7e29db6b0b5bf4c961bc9c9e9772c9

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.2.0
+
+- Validate RIFF/WAVE chunk sizes, 24000 Hz mono 16-bit PCM format and complete aligned nonempty audio data; preserve valid files byte-for-byte and reject malformed downloads without resubmitting.
+
+- Replaced retired synchronous endpoints with public API v1 jobs and separate WAV downloads.
+- Preserved single-voice synthesis and locally encoded base64; added explicit dialogue segments, recovery, cancellation, voices and full quota metadata.
+- Added stable UUID retries, total deadlines, Retry-After handling, terminal/deleted-result validation, response limits and credential-free downloads with no redirects.
+- Rejects unsupported legacy options and labelled script mappings. Requires a paid API subscription/key; retains Ruby 2.6 support.
+
+## 0.1.1
+
+- Previous published synchronous client release, superseded by 0.2.0.

data/README.md

@@ -1,102 +1,110 @@
 # FlowSpeech Ruby
 
-[![Gem Version](https://badge.fury.io/rb/flowspeech.svg)](https://rubygems.org/gems/flowspeech)
-[![Tests](https://github.com/waeckerlinfederowicz66-sketch/flowspeech-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/waeckerlinfederowicz66-sketch/flowspeech-ruby/actions/workflows/test.yml)
-
-A small Ruby client for the [FlowSpeech text to speech API](https://flowspeech.io/). It supports context-aware synthesis, multi-speaker voice assignments, quota checks, audio metadata, and structured API errors.
-
-The gem uses only the Ruby standard library at runtime.
-
-## Installation
-
-Install the gem:
-
-```bash
-gem install flowspeech
-```
-
-Or add it to your Gemfile:
+Ruby 2.6+ client for the [FlowSpeech public API v1](https://flowspeech.io/docs/public-api),
+using only the standard library at runtime. Requires an active paid Basic, Pro
+or Scale subscription (not a trial) and a key from [API settings](https://flowspeech.io/settings/apikeys).
 
 ```ruby
-gem "flowspeech", "~> 0.1"
+gem "flowspeech", "~> 0.2.0"
 ```
 
-Create a FlowSpeech API key, then keep it outside source control:
-
-```bash
-export FLOWSPEECH_API_KEY="your_api_key"
-```
+Set `FLOWSPEECH_API_KEY` through your environment or secret manager. Use this gem
+on your server, never in a public client. Generation consumes account credits.
 
-## Generate speech
+## Generate WAV Audio
 
 ```ruby
 require "flowspeech"
 
 client = FlowSpeech::Client.new
+request_id = SecureRandom.uuid
+# Persist this ID before submitting. Reuse it only with unchanged input.
 audio = client.synthesize(
-  text: "Welcome. [cheerfully] Let's make this sound natural.",
-  speakers: [{ voice_name: "Kore" }]
+  text: "Welcome to FlowSpeech.",
+  speakers: [{ voice_name: "Kore" }],
+  request_id: request_id
 )
-
-audio.write("speech.pcm")
+audio.write("speech.wav")
 puts "#{audio.sample_rate} Hz, #{audio.num_channels} channel"
 ```
 
-The API currently returns base64-encoded linear PCM with format metadata. The 
-`FlowSpeech::Audio#bytes` method returns the decoded bytes without changing the encoding.
+`synthesize` submits a job, polls until `success`, and downloads WAV audio
+(24000 Hz, mono, 16 bit). `audio_base64` is encoded **locally** for compatibility;
+v1 does not return base64 or raw PCM. `Audio` exposes `job_id`, `request_id`,
+`usage`, `bytes`, and `write`. `audio.quota` is no longer populated.
 
-## Multi-speaker dialogue
+## Explicit Dialogue
 
 ```ruby
-audio = client.synthesize(
-  text: "Host: Welcome to the show.\nGuest: Thanks for having me.",
-  speakers: [
-    { speaker: "Host", voice_name: "Charon" },
-    { speaker: "Guest", voice_name: "Kore" }
-  ]
-)
+audio = client.synthesize(segments: [
+  { speaker: "Alice", text: "Welcome!", voice_name: "Kore" },
+  { speaker: "Bob", text: "Thank you.", voice_name: "Puck" }
+])
 ```
 
-## Check quota
+Use `segments` without `text` or `speakers`. Legacy labelled dialogue, multiple
+speaker assignments, and `original_text` are rejected. Segment hashes accept
+`voice_name` or `voiceName`, not both. Unknown fields/options (including model,
+source, speed and output format) are rejected, not silently ignored.
 
-```ruby
-quota = client.quota
-puts "#{quota.fetch("remaining")} characters remaining"
-```
-
-## Error handling
+## Jobs And Recovery
 
 ```ruby
-begin
-  client.synthesize(text: "Hello")
-rescue FlowSpeech::APIError => error
-  warn "#{error.status}: #{error.message}"
-  warn "Retry after #{error.retry_after}s" if error.retryable
-end
+job = client.create_job(text: "Hello", request_id: request_id)
+job = client.wait_job(job)
+File.binwrite("speech.wav", client.download(job))
 ```
 
-## Development
+- `get_job(job_id)` returns a direct v1 job hash.
+- `find_job(request_id)` recovers an interrupted submission by UUID.
+- `cancel_job(job_id)` explicitly cancels server work.
+- `wait_job(job)` polls queued/running/merging/settling; failed/cancelled jobs raise `FlowSpeech::JobError` with `status` and `error_code`.
+- `download(job)` downloads only; retrying it never submits new work.
+- `voices` returns the top-level voice list.
+- `quota` retains the convenience credit hash; `quota_details` preserves the full `quota`, `entitlement`, `subscription`, and `limits` response. Use `quota["available"]` for new work.
+
+The server returns `subscription`; `entitlement` is also accepted for
+compatibility. Neither field is discarded. HTTP 200 is not proof that generation succeeded. A deleted
+result has `status: "success"`, `result: nil`, and `resultDeleted: true`;
+`wait_job`/`download` raise `JobError` with `result_deleted == true`.
+
+`FlowSpeech::Error` carries `request_id`/`job_id` when known. `APIError` adds
+`status`, `error_code` (also `code`, now a string), `retryable`, `retry_after`, and
+`trace_id`. `DeadlineError` means the configured total deadline was reached or
+the required next wait would exceed it. Local interruption does not cancel work.
+
+Recover using the same UUID and input after a lost create response. Do not
+create another recording just because its download failed. Generate a new UUID
+only for intentionally new work.
+
+## Configuration And Security
+
+Constructor options: `api_key`, `base_url`, `open_timeout` (10 seconds),
+`read_timeout` (30), `timeout` (600 total), `poll_interval` (5 minimum),
+`max_retries` (2, allowed 0..10), and `max_download_bytes` (64 MiB).
+All submit/poll/download work shares one total deadline in `synthesize`.
+Network errors, HTTP 429 and retryable 5xx responses get bounded retries with
+the same UUID and body. Longer numeric and HTTP-date `Retry-After` is honored.
+API responses are bounded to 1 MiB; audio is streamed with the byte limit.
+
+Downloads validate the complete RIFF/WAVE container, PCM format (24000 Hz,
+mono, 16 bit), byte rate/block alignment, and nonempty complete sample data.
+Truncated, malformed or mismatched audio is rejected even on HTTP 200. Bounded,
+word-aligned unknown chunks are skipped; valid files are returned unchanged.
+
+API and audio transports are separate. No Bearer token, cookies or idempotency
+key is sent to storage. Redirects are refused for both API and audio requests.
+URLs must be HTTPS without credentials/fragments; HTTP loopback is allowed for
+tests. Optional `transport`, `download_transport` and `sleeper` are trusted test
+hooks; injected transports must not add credentials or follow redirects.
+Audio URLs are public link-access URLs, not private authentication tokens.
 
-Run the tests without real credentials or network requests:
+## Development
 
-```bash
+```sh
 ruby -Ilib test/client_test.rb
-```
-
-Build the gem locally:
-
-```bash
 gem build flowspeech.gemspec
 ```
 
-## Security
-
-- Never commit API keys.
-- Load `FLOWSPEECH_API_KEY` from the environment or a secret manager.
-- The client sends the key only in the `Authorization: Bearer` header.
-- Tests use an injected fake transport and contain no credentials.
-
-## License
-
-MIT
-
+Tests use fake HTTP without keys or generation credits. See [CHANGELOG.md](CHANGELOG.md).
+License: MIT.

data/lib/flowspeech/client.rb

@@ -3,42 +3,50 @@
 require "base64"
 require "json"
 require "net/http"
+require "securerandom"
+require "time"
+require "timeout"
 require "uri"
+require_relative "wav"
 
 module FlowSpeech
-  class Error < StandardError; end
-
+  class Error < StandardError
+    attr_accessor :request_id, :job_id
+  end
+  class DeadlineError < Error; end
+  class JobError < Error
+    attr_reader :status, :error_code, :result_deleted
+    def initialize(job)
+      @status = job["status"]
+      @error_code = job["error"].is_a?(Hash) ? job["error"]["code"] : nil
+      @result_deleted = job["resultDeleted"] == true
+      super(@result_deleted ? "Audio result was deleted (resultDeleted=true)" : "Job #{@status}: #{@error_code}")
+      @request_id, @job_id = job["requestId"], job["id"]
+    end
+  end
   class APIError < Error
-    attr_reader :status, :code, :error_code, :retryable, :retry_after
-
-    def initialize(message, status:, code: nil, error_code: nil, retryable: false, retry_after: nil)
+    attr_reader :status, :code, :error_code, :retryable, :retry_after, :trace_id
+    def initialize(message, status:, code: nil, error_code: nil, retryable: false, retry_after: nil, trace_id: nil)
       super(message)
-      @status = status
-      @code = code
-      @error_code = error_code
-      @retryable = retryable
-      @retry_after = retry_after
+      @status, @code, @error_code = status, code, error_code || code
+      @retryable, @retry_after, @trace_id = retryable, retry_after, trace_id
     end
   end
 
   class Audio
-    attr_reader :mime_type, :audio_base64, :quota, :sample_rate, :num_channels, :bits_per_sample
-
+    attr_reader :mime_type, :audio_base64, :quota, :sample_rate, :num_channels,
+                :bits_per_sample, :job_id, :request_id, :usage
     def initialize(data)
-      @mime_type = data.fetch("mimeType")
-      @audio_base64 = data.fetch("audioBase64")
-      @quota = data["quota"]
-      @sample_rate = data.fetch("sampleRate")
-      @num_channels = data.fetch("numChannels")
-      @bits_per_sample = data.fetch("bitsPerSample")
+      @mime_type, @audio_base64 = data.fetch("mimeType"), data.fetch("audioBase64")
+      @quota, @sample_rate = data["quota"], data.fetch("sampleRate")
+      @num_channels, @bits_per_sample = data.fetch("numChannels"), data.fetch("bitsPerSample")
+      @job_id, @request_id, @usage = data["jobId"], data["requestId"], data["usage"]
     end
-
     def bytes
       Base64.strict_decode64(audio_base64)
-    rescue ArgumentError => e
-      raise Error, "FlowSpeech returned invalid base64 audio: #{e.message}"
+    rescue ArgumentError
+      raise Error, "Invalid local base64 audio"
     end
-
     def write(path)
       File.binwrite(path, bytes)
       path
@@ -47,110 +55,360 @@ module FlowSpeech
 
   class Client
     DEFAULT_BASE_URL = "https://flowspeech.io"
+    JOBS = "/api/v1/tts/jobs"
+    UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+    PENDING = %w[queued running merging settling].freeze
+    Response = Struct.new(:code, :body, :headers) do
+      def [](name)
+        headers[name.downcase]
+      end
+    end
 
+    # Transports are trusted injection points. A download transport must not
+    # add authentication, cookies or redirect handling of its own.
     def initialize(api_key: ENV["FLOWSPEECH_API_KEY"], base_url: DEFAULT_BASE_URL,
-                   open_timeout: 10, read_timeout: 90, transport: nil)
-      @api_key = api_key.to_s.strip
-      @base_url = URI(base_url)
-      @open_timeout = open_timeout
-      @read_timeout = read_timeout
-      @transport = transport
-
-      raise ArgumentError, "api_key is required" if @api_key.empty?
-      unless @base_url.is_a?(URI::HTTP) && @base_url.host
-        raise ArgumentError, "base_url must be an HTTP or HTTPS URL"
+                   open_timeout: 10, read_timeout: 30, timeout: 600,
+                   poll_interval: 5, max_retries: 2, max_download_bytes: 64 * 1024 * 1024,
+                   transport: nil, download_transport: nil, sleeper: nil)
+      unless api_key.is_a?(String) && !api_key.empty? && !api_key.match?(/\s/)
+        raise ArgumentError, "api_key must be nonempty and contain no whitespace"
+      end
+      @api_key = api_key
+      @base_url = safe_url(base_url)
+      unless ["", "/"].include?(@base_url.path) && !@base_url.query
+        raise ArgumentError, "base_url must be an origin"
+      end
+      [open_timeout, read_timeout, timeout, poll_interval].each do |value|
+        raise ArgumentError, "timeouts must be finite and positive" unless value.is_a?(Numeric) && value.finite? && value > 0
+      end
+      raise ArgumentError, "poll_interval must be at least five seconds" if poll_interval < 5
+      raise ArgumentError, "max_retries must be 0..10" unless max_retries.is_a?(Integer) && (0..10).cover?(max_retries)
+      unless max_download_bytes.is_a?(Integer) && (1..(1 << 30)).cover?(max_download_bytes)
+        raise ArgumentError, "max_download_bytes must be 1..1073741824"
       end
+      @open_timeout, @read_timeout, @timeout = open_timeout, read_timeout, timeout
+      @poll_interval, @max_retries, @max_download_bytes = poll_interval, max_retries, max_download_bytes
+      @transport, @download_transport = transport, download_transport
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
     end
 
     def quota
-      request(:get, "/api/ai/text-to-speech/quota").fetch("quota")
+      quota_details.fetch("quota")
     end
 
-    def synthesize(text:, speakers: [{ voice_name: "Kore" }], original_text: nil)
-      raise ArgumentError, "text is required" if text.to_s.strip.empty?
+    # Preserves both entitlement (contract) and subscription (server alias).
+    def quota_details
+      operation do |deadline|
+        data = request(:get, "/api/v1/quota", deadline: deadline).first
+        raise Error, "Missing quota" unless data["quota"].is_a?(Hash)
+        data
+      end
+    end
 
-      normalized_speakers = Array(speakers).map { |speaker| normalize_speaker(speaker) }
-      raise ArgumentError, "at least one speaker is required" if normalized_speakers.empty?
+    def voices
+      operation do |deadline|
+        data = request(:get, "/api/v1/voices", deadline: deadline).first
+        raise Error, "Missing voices" unless data["voices"].is_a?(Array)
+        data["voices"]
+      end
+    end
 
-      data = request(
-        :post,
-        "/api/ai/text-to-speech",
-        text: text,
-        originalText: original_text || text,
-        speakers: normalized_speakers
-      )
-      raise Error, "FlowSpeech response did not include audio" if data["audioBase64"].to_s.empty?
+    def create_job(text: nil, speakers: nil, voice_name: "Kore", segments: nil, original_text: nil, request_id: nil)
+      input = normalize_input(text, speakers, voice_name, segments, original_text)
+      id = checked_id(request_id || SecureRandom.uuid)
+      operation(request_id: id) { |deadline| submit(input, id, deadline) }
+    end
+
+    def get_job(id)
+      checked_id(id)
+      operation(job_id: id) { |deadline| get(id, deadline) }
+    end
+
+    def find_job(request_id)
+      checked_id(request_id)
+      operation(request_id: request_id) do |deadline|
+        job = job_request(:get, "#{JOBS}?requestId=#{request_id}", deadline: deadline)
+        match_request(job, request_id)
+      end
+    end
+
+    def cancel_job(id)
+      checked_id(id)
+      operation(job_id: id) do |deadline|
+        job = job_request(:post, "#{JOBS}/#{id}/cancel", deadline: deadline)
+        raise Error, "Job ID mismatch" unless job["id"].casecmp(id).zero?
+        job
+      end
+    end
 
-      Audio.new(data)
+    def wait_job(job)
+      validate_job(job)
+      operation(request_id: job["requestId"], job_id: job["id"]) { |deadline| await_job(job, deadline) }
+    end
+
+    # Retrying this method never creates a new job.
+    def download(job)
+      validate_job(job)
+      operation(request_id: job["requestId"], job_id: job["id"]) { |deadline| download_bytes(job, deadline) }
+    end
+
+    def synthesize(text: nil, speakers: nil, voice_name: "Kore", segments: nil, original_text: nil, request_id: nil)
+      input = normalize_input(text, speakers, voice_name, segments, original_text)
+      id = checked_id(request_id || SecureRandom.uuid)
+      job = nil
+      operation(request_id: id) do |deadline|
+        job = submit(input, id, deadline)
+        job = await_job(job, deadline)
+        bytes = download_bytes(job, deadline)
+        Audio.new(job["result"].merge("audioBase64" => Base64.strict_encode64(bytes),
+          "numChannels" => job["result"]["channels"], "jobId" => job["id"], "requestId" => id, "usage" => job["usage"]))
+      end
+    rescue Error => error
+      error.job_id ||= job && job["id"]
+      raise
     end
 
     private
 
-    def normalize_speaker(speaker)
-      input = speaker.respond_to?(:to_h) ? speaker.to_h : {}
-      voice_name = input[:voice_name] || input["voice_name"] || input[:voiceName] || input["voiceName"]
-      raise ArgumentError, "every speaker requires voice_name" if voice_name.to_s.strip.empty?
+    def normalize_input(text, speakers, voice, segments, original)
+      raise ArgumentError, "original_text is unsupported by v1" unless original.nil?
+      unless segments.nil?
+        unless segments.is_a?(Array) && !segments.empty? && text.nil? && speakers.nil?
+          raise ArgumentError, "Use nonempty segments without text or speakers"
+        end
+        return { "mode" => "multi", "segments" => segments.map { |s| normalize_segment(s) } }
+      end
+      if speakers
+        unless speakers.is_a?(Array) && speakers.length == 1
+          raise ArgumentError, "Use explicit segments for multiple speakers"
+        end
+        s = normalize_keys(speakers.first, %w[voice_name voiceName])
+        voice = s["voiceName"] || s["voice_name"]
+      end
+      required_string(text, "text")
+      required_string(voice, "voiceName")
+      { "mode" => "single", "text" => text, "voiceName" => voice }
+    end
+
+    def normalize_segment(segment)
+      s = normalize_keys(segment, %w[speaker text voiceName voice_name])
+      s["voiceName"] ||= s.delete("voice_name")
+      %w[speaker text voiceName].each { |key| required_string(s[key], key) }
+      s
+    end
 
-      result = { voiceName: voice_name }
-      label = input[:speaker] || input["speaker"]
-      result[:speaker] = label unless label.to_s.strip.empty?
+    def normalize_keys(value, allowed)
+      raise ArgumentError, "Expected a hash" unless value.is_a?(Hash)
+      result = {}
+      value.each do |key, v|
+        key = key.to_s
+        raise ArgumentError, "Unsupported or duplicate input field: #{key}" unless allowed.include?(key) && !result.key?(key)
+        result[key] = v
+      end
+      if result.key?("voiceName") && result.key?("voice_name")
+        raise ArgumentError, "Specify only one voice name field"
+      end
       result
     end
 
-    def request(method, path, payload = nil)
-      uri = @base_url + path
-      http_request = build_request(method, uri, payload)
-      response = @transport ? @transport.call(uri, http_request) : perform(uri, http_request)
-      parsed = parse_json(response.body)
+    def required_string(value, name)
+      raise ArgumentError, "#{name} must be a nonempty string" unless value.is_a?(String) && !value.strip.empty?
+    end
+
+    def checked_id(id)
+      raise ArgumentError, "ID must be a UUID" unless id.is_a?(String) && UUID.match?(id)
+      id
+    end
 
-      unless response.code.to_i.between?(200, 299)
-        error_data = parsed["data"].is_a?(Hash) ? parsed["data"] : {}
-        message = parsed["message"].to_s.strip
-        message = "FlowSpeech request failed with HTTP #{response.code}" if message.empty?
-        raise APIError.new(
-          message,
-          status: response.code.to_i,
-          code: parsed["code"],
-          error_code: error_data["errorCode"],
-          retryable: error_data["retryable"] == true,
-          retry_after: response["Retry-After"]
-        )
+    def safe_url(raw)
+      uri = URI(raw)
+      unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.fragment &&
+             (uri.scheme == "https" || (uri.scheme == "http" && %w[localhost 127.0.0.1 ::1].include?(uri.hostname)))
+        raise ArgumentError, "URL must be HTTPS without credentials or fragment; HTTP loopback is allowed for tests"
       end
+      uri
+    rescue URI::InvalidURIError, TypeError
+      raise ArgumentError, "Invalid URL"
+    end
 
-      unless parsed["code"] == 0 && parsed["data"].is_a?(Hash)
-        raise Error, parsed["message"].to_s.empty? ? "Unexpected FlowSpeech response" : parsed["message"]
+    def operation(request_id: nil, job_id: nil)
+      deadline = monotonic + @timeout
+      Timeout.timeout(@timeout, DeadlineError) { yield deadline }
+    rescue Error => error
+      error.request_id ||= request_id
+      error.job_id ||= job_id
+      raise
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def remaining(deadline)
+      value = deadline - monotonic
+      raise DeadlineError, "Operation deadline exceeded" if value <= 0
+      value
+    end
+
+    def pause(raw, deadline)
+      delay = @poll_interval
+      if raw.to_s.match?(/\A\d+\z/)
+        delay = [delay, raw.to_i].max
+      elsif raw
+        begin
+          delay = [delay, Time.httpdate(raw) - Time.now].max
+        rescue ArgumentError
+          # Invalid Retry-After uses the conservative polling interval.
+        end
       end
+      raise DeadlineError, "Retry or poll wait would exceed operation deadline" if delay >= remaining(deadline)
+      @sleeper.call(delay)
+      remaining(deadline)
+    end
 
-      parsed["data"]
+    def submit(input, id, deadline)
+      job = job_request(:post, JOBS, body: JSON.generate("input" => input), id: id, deadline: deadline)
+      match_request(job, id)
     end
 
-    def build_request(method, uri, payload)
-      request_class = method == :get ? Net::HTTP::Get : Net::HTTP::Post
-      request = request_class.new(uri)
-      request["Authorization"] = "Bearer #{@api_key}"
-      request["Accept"] = "application/json"
-      if payload
-        request["Content-Type"] = "application/json"
-        request.body = JSON.generate(payload)
+    def match_request(job, id)
+      if job["requestId"] && !job["requestId"].casecmp(id).zero?
+        raise Error, "Request ID mismatch"
       end
-      request
+      job["requestId"] = id
+      job
     end
 
-    def perform(uri, request)
-      Net::HTTP.start(
-        uri.host,
-        uri.port,
-        use_ssl: uri.scheme == "https",
-        open_timeout: @open_timeout,
-        read_timeout: @read_timeout
-      ) { |http| http.request(request) }
+    def get(id, deadline)
+      job = job_request(:get, "#{JOBS}/#{id}", deadline: deadline)
+      raise Error, "Job ID mismatch" unless job["id"].casecmp(id).zero?
+      job
     end
 
-    def parse_json(body)
-      JSON.parse(body.to_s)
-    rescue JSON::ParserError => e
-      raise Error, "FlowSpeech returned invalid JSON: #{e.message}"
+    def job_request(method, path, body: nil, id: nil, deadline:)
+      job, retry_after = request(method, path, body: body, id: id, deadline: deadline)
+      validate_job(job)
+      job["retryAfter"] = retry_after
+      job
+    end
+
+    def validate_job(job)
+      unless job.is_a?(Hash) && job["id"].is_a?(String) && UUID.match?(job["id"])
+        raise Error, "Missing or invalid job ID"
+      end
+      if job.key?("requestId") && (!job["requestId"].is_a?(String) || !UUID.match?(job["requestId"]))
+        raise Error, "Invalid request ID"
+      end
+      if job.key?("resultDeleted") && ![true, false].include?(job["resultDeleted"])
+        raise Error, "Invalid resultDeleted flag"
+      end
+      status = job["status"]
+      raise Error, "Unknown job status" unless (PENDING + %w[success failed cancelled]).include?(status)
+      return job unless status == "success"
+      return job if job["resultDeleted"] == true && job["result"].nil?
+      result = job["result"]
+      unless job["resultDeleted"] != true && result.is_a?(Hash) && result["mimeType"] == "audio/wav" &&
+             result["sampleRate"] == 24000 && result["channels"] == 1 && result["bitsPerSample"] == 16
+        raise Error, "Missing or malformed WAV result"
+      end
+      safe_url(result["url"])
+      job
+    rescue ArgumentError
+      raise Error, "Invalid audio URL"
+    end
+
+    def await_job(job, deadline)
+      id, request_id = job["id"], job["requestId"]
+      loop do
+        remaining(deadline)
+        if PENDING.include?(job["status"])
+          pause(job["retryAfter"], deadline)
+          job = get(id, deadline)
+          match_request(job, request_id) if request_id
+        elsif job["status"] == "success" && job["resultDeleted"] != true
+          return job
+        else
+          raise JobError, job
+        end
+      end
+    end
+
+    def download_bytes(job, deadline)
+      raise JobError, job unless job["status"] == "success" && job["resultDeleted"] != true
+      uri = safe_url(job.fetch("result").fetch("url"))
+      req = Net::HTTP::Get.new(uri)
+      response = exchange(uri, req, deadline, @max_download_bytes, @download_transport)
+      raise Error, "Download HTTP #{response.code}; retry download with the same job" unless response.code.to_i == 200
+      Wav.validate!(response.body.to_s) { remaining(deadline) }
+    rescue IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError
+      raise Error, "Audio download failed; retry download with the same job"
+    end
+
+    def request(method, path, body: nil, id: nil, deadline:)
+      uri = @base_url + path
+      attempts = 0
+      loop do
+        retry_after = nil
+        begin
+          req = (method == :get ? Net::HTTP::Get : Net::HTTP::Post).new(uri)
+          req["Authorization"] = "Bearer #{@api_key}"
+          req["Accept"] = "application/json"
+          req["Idempotency-Key"] = id if id
+          if body
+            req["Content-Type"] = "application/json"
+            req.body = body
+          end
+          response = exchange(uri, req, deadline, 1024 * 1024, @transport)
+          status = response.code.to_i
+          retry_after = response["Retry-After"]
+          data = begin
+            JSON.parse(response.body.to_s)
+          rescue JSON::ParserError
+            nil
+          end
+          if (200..299).cover?(status)
+            raise Error, "Invalid JSON object response" unless data.is_a?(Hash)
+            return [data, retry_after]
+          end
+          detail = data.is_a?(Hash) && data["error"].is_a?(Hash) ? data["error"] : {}
+          error = APIError.new(detail["message"] || "HTTP #{status}", status: status,
+            code: detail["code"], retryable: detail["retryable"] == true, retry_after: retry_after,
+            trace_id: data.is_a?(Hash) ? data["traceId"] || response["X-Request-Id"] : response["X-Request-Id"])
+          raise error unless status == 429 || (status >= 500 && error.retryable)
+        rescue IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError
+          error = Error.new("API transport failed")
+        end
+        raise error if attempts >= @max_retries
+        attempts += 1
+        pause(retry_after, deadline)
+      end
+    end
+
+    def exchange(uri, request, deadline, limit, transport)
+      remaining(deadline)
+      response = if transport
+        transport.call(uri, request)
+      else
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+          open_timeout: [@open_timeout, remaining(deadline)].min,
+          read_timeout: [@read_timeout, remaining(deadline)].min) do |http|
+          http.max_retries = 0 if http.respond_to?(:max_retries=)
+          result = nil
+          http.request(request) do |res|
+            bytes = String.new(encoding: Encoding::BINARY)
+            res.read_body do |chunk|
+              remaining(deadline)
+              raise Error, "Response exceeds byte limit" if bytes.bytesize + chunk.bytesize > limit
+              bytes << chunk
+            end
+            result = Response.new(res.code, bytes, res.to_hash.transform_values(&:first))
+          end
+          result
+        end
+      end
+      remaining(deadline)
+      raise Error, "Response exceeds byte limit" if response.body.to_s.bytesize > limit
+      response
     end
   end
 end
-

data/lib/flowspeech/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FlowSpeech
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/flowspeech/wav.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FlowSpeech
+  module Wav
+    # Walk bounded chunks, preserving the original file and its sample bytes.
+    def self.validate!(bytes)
+      invalid = -> { raise Error, "Invalid WAV: expected complete 24000 Hz mono 16-bit PCM with nonempty aligned data" }
+      invalid.call unless bytes.bytesize >= 12 && bytes.byteslice(0, 4) == "RIFF" && bytes.byteslice(8, 4) == "WAVE"
+      invalid.call unless bytes.byteslice(4, 4).unpack1("V") + 8 == bytes.bytesize
+      offset, format_seen, data_seen = 12, false, false
+      while offset < bytes.bytesize
+        yield if block_given?
+        invalid.call if bytes.bytesize - offset < 8
+        tag = bytes.byteslice(offset, 4)
+        size = bytes.byteslice(offset + 4, 4).unpack1("V")
+        start = offset + 8
+        finish = start + size
+        following = finish + (size & 1)
+        invalid.call if following > bytes.bytesize
+        case tag
+        when "fmt "
+          invalid.call if format_seen || data_seen || ![16, 18].include?(size)
+          fields = bytes.byteslice(start, 16).unpack("vvVVvv")
+          invalid.call unless fields == [1, 1, 24000, 48000, 2, 16]
+          invalid.call if size == 18 && bytes.byteslice(start + 16, 2).unpack1("v") != 0
+          format_seen = true
+        when "data"
+          invalid.call unless format_seen && !data_seen && size > 0 && size.even?
+          data_seen = true
+        end
+        offset = following
+      end
+      invalid.call unless format_seen && data_seen
+      yield if block_given?
+      bytes
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flowspeech
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - FlowSpeech
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -30,19 +30,21 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '14'
-description: Generate context-aware speech, multi-speaker dialogue, and audio metadata
-  with FlowSpeech.
+description: FlowSpeech public API v1 jobs, polling, recovery, multi-speaker segments
+  and credential-free WAV downloads.
 email:
 - support@flowspeech.io
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/flowspeech.rb
 - lib/flowspeech/client.rb
 - lib/flowspeech/version.rb
+- lib/flowspeech/wav.rb
 homepage: https://flowspeech.io/
 licenses:
 - MIT
@@ -51,7 +53,7 @@ metadata:
   source_code_uri: https://github.com/waeckerlinfederowicz66-sketch/flowspeech-ruby
   changelog_uri: https://github.com/waeckerlinfederowicz66-sketch/flowspeech-ruby/releases
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -67,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.5.22
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Ruby client for the FlowSpeech text-to-speech API
 test_files: []