transcriptdock 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a09a930e042d046cad520ea28c34cfa11be1420fea7781f1f34f24d0e4c728ae
+  data.tar.gz: 4902cb250c049366cbf60f284a172a6dceaee2f0978bda5cf3d37585db07a5b8
+SHA512:
+  metadata.gz: fbfd77ef2cac8034add09db092c66b96166c2a3ec566cb8e98c0f0260bf61f87a739eb0723c6425f975d7bae47692e8749e7262d9e0038793dbe9b48c84d3130
+  data.tar.gz: 42b9466688bb81cf72f1097f297c7965ab01e28511f66573ca60bcf6e66edb4e3302c39a0cc52ead64900a5696fce2273709eae98eb5def0eb77b84d8e85a937

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Transcript Dock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,65 @@
+# Transcript Dock for Ruby
+
+A synchronous client using Ruby's standard libraries. Requires Ruby 3.2 or
+newer. Version 0.1.0.
+
+Install:
+
+```sh
+gem install transcriptdock
+```
+
+```ruby
+require 'transcriptdock'
+require 'securerandom'
+
+client = TranscriptDock::Client.new(ENV.fetch('TRANSCRIPTDOCK_API_KEY'))
+# Generate once per intended operation; save with the returned job ID.
+key = SecureRandom.uuid
+job = client.create_job(
+  {source: {url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'},
+   mode: 'captions_only', max_credits: 1},
+  idempotency_key: key
+)
+job = client.wait_for_job(job['id'], timeout: 120)
+if job['status'] == 'succeeded'
+  puts client.export_transcript(job['result_id'], format: 'srt')
+end
+```
+
+Creating a job can spend credits. This example requests captions only with a
+one credit ceiling. It does not enable AI fallback. Save the operation key and
+reuse the exact body and same key to recover a lost response. There are no
+automatic retries, including in the underlying HTTP transport.
+
+`capabilities`, `create_job`, `get_job`, `get_transcript`, `export_transcript`
+and `wait_for_job` provide the core flow. All public endpoints are available
+through `request(method, path, body: nil, query: {}, idempotency_key: nil)`.
+Use the exact fields in the [API contract](https://www.transcriptdock.com/docs/openapi.yaml)
+for batches, discovery, usage, upload slots and webhook endpoints.
+
+Responses are hashes retaining future fields and original timing units.
+Exports return the raw JSON, TXT, SRT or VTT string. Polling returns failed and
+cancelled terminal jobs normally; inspect status first. `JobTimeoutError#job`
+retains the last observed response. `ApiError` exposes `code`, `status`,
+`retryable`, `request_id` and `retry_after_seconds`. Error messages redact bearer
+keys and do not expose raw gateway pages.
+
+The default per request timeout is 30 seconds. The constructor accepts
+`base_url:` and `timeout:`. Custom origins require HTTPS, except loopback HTTP
+for development. Redirects are not followed. Upload signed storage URLs
+separately without the API key. Store webhook secrets privately and implement
+callback signature checks following the API documentation.
+
+## Check and build
+
+From the application repository root with Ruby and Python 3 installed:
+
+```sh
+python3 .ci/check.py
+mkdir -p dist
+gem build transcriptdock.gemspec --output dist/transcriptdock-0.1.0.gem
+```
+
+The shared fixture uses loopback HTTP and spends no credits. No lockfile is
+needed for third party dependencies because this library has none. Release workflow: https://github.com/TranscriptDock/transcriptdock-ruby/actions.

data/lib/transcriptdock.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+require 'net/http'
+require 'json'
+require 'uri'
+require 'ipaddr'
+
+module TranscriptDock
+  VERSION = '0.1.0'
+
+  class ApiError < StandardError
+    attr_reader :code, :status, :retryable, :request_id, :retry_after_seconds
+    def initialize(code, message, status: nil, retryable: false, request_id: nil, retry_after_seconds: nil)
+      super(message)
+      @code, @status, @retryable = code, status, retryable
+      @request_id, @retry_after_seconds = request_id, retry_after_seconds
+    end
+  end
+
+  class JobTimeoutError < StandardError
+    attr_reader :job
+    def initialize(job)
+      super('The job is still running. Check it again using its ID.')
+      @job = job
+    end
+  end
+
+  class Client
+    def initialize(api_key, base_url: 'https://www.transcriptdock.com', timeout: 30)
+      raise ArgumentError, 'Provide an API key without whitespace or control characters.' unless api_key.is_a?(String) && api_key.match?(/\A[!-~]+\z/)
+      origin = URI.parse(base_url)
+      begin
+        loopback = origin.hostname == 'localhost' || IPAddr.new(origin.hostname).loopback?
+      rescue IPAddr::InvalidAddressError, ArgumentError
+        loopback = false
+      end
+      unless origin.is_a?(URI::HTTP) && origin.hostname && (origin.scheme == 'https' || (origin.scheme == 'http' && loopback)) && origin.userinfo.nil? && origin.query.nil? && origin.fragment.nil? && ['', '/'].include?(origin.path)
+        raise ArgumentError, 'Use an HTTPS origin, or loopback HTTP, without credentials, path, query or fragment.'
+      end
+      @api_key, @base_url = api_key, base_url.sub(%r{/\z}, '')
+      @timeout = positive(timeout, 'timeout')
+    rescue URI::InvalidURIError
+      raise ArgumentError, 'Provide a valid API origin.'
+    end
+
+    def request(method, path, body: nil, query: {}, idempotency_key: nil, text: false, timeout: @timeout)
+      raise ArgumentError, 'Provide a supported HTTP method.' unless method.is_a?(String) && %w[GET POST PUT PATCH DELETE HEAD OPTIONS].include?(method.upcase)
+      method = method.upcase
+      unless path.is_a?(String) && path.start_with?('/v1/') && !path.match?(/[?#\\]/) && !URI::DEFAULT_PARSER.unescape(path).split('/').any? { |s| ['.', '..'].include?(s) }
+        raise ArgumentError, 'Use a /v1/ path and pass query parameters separately.'
+      end
+      needs_key = method == 'POST' && (%w[/v1/jobs /v1/batches /v1/video-discoveries /v1/language-discoveries].include?(path) || path.end_with?('/retry'))
+      if needs_key || !idempotency_key.nil?
+        raise ArgumentError, 'Idempotency keys need 8 to 128 printable ASCII characters.' unless idempotency_key.is_a?(String) && idempotency_key.match?(/\A[ -~]{8,128}\z/)
+      end
+      uri = URI.parse(@base_url + path)
+      uri.query = URI.encode_www_form(query.reject { |_, v| v.nil? }) unless query.empty?
+      headers = {'Authorization' => "Bearer #{@api_key}", 'Accept' => 'application/json', 'User-Agent' => "transcriptdock-ruby/#{VERSION}"}
+      headers['Idempotency-Key'] = idempotency_key if idempotency_key
+      headers['Content-Type'] = 'application/json' unless body.nil?
+      req = Net::HTTPGenericRequest.new(method, !body.nil?, method != 'HEAD', uri.request_uri, headers)
+      req.body = JSON.generate(body) unless body.nil?
+      http = Net::HTTP.new(uri.hostname, uri.port, nil)
+      http.use_ssl = uri.scheme == 'https'
+      http.max_retries = 0
+      http.open_timeout = http.read_timeout = http.write_timeout = positive(timeout, 'timeout')
+      begin
+        response = http.start { |connection| connection.request(req) }
+      rescue IOError, SystemCallError, Timeout::Error, SocketError, OpenSSL::SSL::SSLError
+        raise ApiError.new('NETWORK_ERROR', 'Could not reach the API. Check the job before retrying a submission.', retryable: true), cause: nil
+      end
+      status = response.code.to_i
+      if status < 200 || status >= 300
+        begin
+          envelope = JSON.parse(response.body)
+        rescue JSON::ParserError
+          envelope = {}
+        end
+        envelope = {} unless envelope.is_a?(Hash)
+        error = envelope['error'].is_a?(Hash) ? envelope['error'] : {}
+        raise ApiError.new(redact(error['code'] || 'HTTP_ERROR'), redact(error['message'] || "Request failed with status #{status}."), status: status,
+          retryable: error.fetch('retryable', status == 429 || status >= 500), request_id: envelope['request_id'] && redact(envelope['request_id']), retry_after_seconds: error['retry_after_seconds'])
+      end
+      return response.body if text
+      begin
+        result = JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise ApiError.new('INVALID_RESPONSE', 'The API did not return JSON.'), cause: nil
+      end
+      raise ApiError.new('INVALID_RESPONSE', 'The API did not return a JSON object.') unless result.is_a?(Hash)
+      result
+    end
+
+    def capabilities = request('GET', '/v1/capabilities')
+    def create_job(body, idempotency_key:) = request('POST', '/v1/jobs', body: body, idempotency_key: idempotency_key)
+    def get_job(id) = request('GET', "/v1/jobs/#{encode_id(id)}")
+    def get_transcript(id) = request('GET', "/v1/transcripts/#{encode_id(id)}")
+    def export_transcript(id, format: 'txt')
+      raise ArgumentError, 'Choose json, txt, srt or vtt.' unless %w[json txt srt vtt].include?(format)
+      request('GET', "/v1/transcripts/#{encode_id(id)}/export", query: {format: format}, text: true)
+    end
+
+    def wait_for_job(id, timeout: 120, poll_interval: 3)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + positive(timeout, 'timeout')
+      positive(poll_interval, 'poll_interval')
+      last = nil
+      loop do
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise JobTimeoutError, last if remaining <= 0
+        last = request('GET', "/v1/jobs/#{encode_id(id)}", timeout: [remaining, @timeout].min)
+        return last if %w[succeeded failed cancelled].include?(last['status'])
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise JobTimeoutError, last if remaining <= 0
+        sleep [remaining, poll_interval].min
+      end
+    end
+
+    private
+    def positive(value, name)
+      raise ArgumentError, "#{name} must be a finite positive number." unless value.is_a?(Numeric) && value.finite? && value > 0
+      value
+    end
+    def encode_id(id)
+      raise ArgumentError, 'Provide a nonempty ID.' unless id.is_a?(String) && !id.empty? && !['.', '..'].include?(id)
+      URI.encode_www_form_component(id).gsub('+', '%20')
+    end
+    def redact(value)
+      value.to_s.gsub(@api_key, '[REDACTED]').gsub(/td_live_[A-Za-z0-9_-]+|Bearer\s+\S+/i, '[REDACTED]')
+    end
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: transcriptdock
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Transcript Dock
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-15 00:00:00.000000000 Z
+dependencies: []
+description: Standard library client for timed transcripts, jobs and the public Transcript
+  Dock API.
+email: transcriptdock@volods.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/transcriptdock.rb
+homepage: https://www.transcriptdock.com/docs
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://www.transcriptdock.com/docs
+  source_code_uri: https://github.com/TranscriptDock/transcriptdock-ruby
+  bug_tracker_uri: https://github.com/TranscriptDock/transcriptdock-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby client for the Transcript Dock transcription API
+test_files: []