lara-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f327f84f1775f706e868dcb2a843ce2074778a988e35a5b56949301df4b9fb9b
+  data.tar.gz: 8cc17e63bf6f79b0b85e273f2559873985339a1eab1948529a195fd59b164b47
+SHA512:
+  metadata.gz: 2d962b4da02a66c126dfcd0740a5fd7894e125d9a97d0f016ac6dab3d41136b1025db02549b95c19a86a3a9253d0a154ab44b6171b8dce06a7a4a392f258b41b
+  data.tar.gz: 86f152fc3c6891561a9cc4d0f18696d86451cd130023bd1d186ac1cb261fed3b04837ff1c59096075af66f753800c1fc27c0ec7b878e03192c45549b85ad4ca7

data/lib/lara/audio.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Lara
+  class AudioTranslator
+    ALLOWED_AUDIO_PARAMS = %i[
+      id
+      status
+      target
+      filename
+      source
+      created_at
+      updated_at
+      options
+      translated_seconds
+      total_seconds
+      error_reason
+    ].freeze
+
+    def initialize(client, s3_client = S3Client.new)
+      @client = client
+      @s3 = s3_client
+      @polling_interval = 2
+    end
+
+    # Uploads an audio file to S3 and creates a translation job.
+    # @return [Lara::Models::Audio]
+    def upload(file_path:, filename:, target:, source: nil, adapt_to: nil, glossaries: nil,
+               no_trace: false, style: nil)
+      response_data = @client.get("/v2/audio/upload-url", params: { filename: filename })
+      url = response_data["url"]
+      fields = response_data["fields"]
+
+      @s3.upload(url: url, fields: fields, io: file_path)
+
+      body = {
+        s3key: fields["key"],
+        target: target,
+        source: source,
+        adapt_to: adapt_to,
+        glossaries: glossaries,
+        style: style
+      }.compact
+
+      headers = {}
+      headers["X-No-Trace"] = "true" if no_trace
+
+      response = @client.post("/v2/audio/translate", body: body, headers: headers)
+      response_params = response.transform_keys(&:to_sym)
+      Lara::Models::Audio.new(**filter_audio_params(response_params))
+    end
+
+    # Fetch audio translation status.
+    # @return [Lara::Models::Audio]
+    def status(id)
+      response = @client.get("/v2/audio/#{id}")
+      response_params = response.transform_keys(&:to_sym)
+      Lara::Models::Audio.new(**filter_audio_params(response_params))
+    end
+
+    # Download translated audio bytes.
+    # @return [String] bytes
+    def download(id)
+      url = @client.get("/v2/audio/#{id}/download-url")["url"]
+      @s3.download(url: url)
+    end
+
+    # Translates an audio file end-to-end
+    # @return [String] translated audio bytes
+    def translate(file_path:, filename:, target:, source: nil, adapt_to: nil, glossaries: nil,
+                  no_trace: false, style: nil)
+      audio = upload(file_path: file_path, filename: filename, target: target, source: source,
+                     adapt_to: adapt_to, glossaries: glossaries, no_trace: no_trace, style: style)
+
+      max_wait_time = 60 * 15 # 15 minutes
+      start = Time.now
+
+      loop do |_|
+        current = status(audio.id)
+
+        case current.status
+        when Lara::Models::AudioStatus::TRANSLATED
+          return download(current.id)
+        when Lara::Models::AudioStatus::ERROR
+          raise Lara::LaraApiError.new(500, "AudioError",
+                                       current.error_reason || "Unknown error")
+        end
+
+        raise Timeout::Error if Time.now - start > max_wait_time
+
+        sleep @polling_interval
+      end
+    end
+
+    private
+
+    def filter_audio_params(params)
+      params.slice(*ALLOWED_AUDIO_PARAMS)
+    end
+  end
+end

data/lib/lara/auth_token.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Lara
+  # JWT authentication token for API access
+  class AuthToken
+    attr_reader :token, :refresh_token
+
+    def initialize(token, refresh_token)
+      @token = token
+      @refresh_token = refresh_token
+    end
+
+    def to_s
+      token
+    end
+  end
+end

data/lib/lara/client.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "json"
+require "openssl"
+require "base64"
+require "digest"
+require "uri"
+
+module Lara
+  # This class is used to interact with Lara via the REST API.
+
+  class Client
+    DEFAULT_BASE_URL = "https://api.laratranslate.com"
+
+    def initialize(auth_method, base_url: DEFAULT_BASE_URL, connection_timeout: nil,
+                   read_timeout: nil)
+      case auth_method
+      when Credentials
+        @credentials = auth_method
+        @auth_token = nil
+      when AuthToken
+        @credentials = nil
+        @auth_token = auth_method
+      else
+        raise ArgumentError, "auth_method must be Credentials or AuthToken"
+      end
+
+      @base_url = base_url.to_s.sub(%r{/+$}, "")
+      @connection_timeout = connection_timeout
+      @read_timeout = read_timeout
+      @extra_headers = {}
+      @auth_mutex = Mutex.new
+
+      @connection = build_connection
+    end
+
+    attr_reader :base_url
+
+    # Sets an extra header
+    # @param name [String] Header name
+    # @param value [String] Header value
+    def set_extra_header(name, value)
+      @extra_headers[name] = value
+    end
+
+    # Sends a GET request to the Lara API.
+    # @param path [String] The path to send the request to.
+    # @param params [Hash,nil] The parameters to send with the request.
+    # @param headers [Hash,nil] Additional headers to include in the request.
+    # @return [Hash, Array, String, nil] The JSON 'content' from the API or CSV body for csv responses.
+    def get(path, params: nil, headers: nil)
+      request(:get, path, body: nil, headers: headers, params: params)
+    end
+
+    # Sends a POST request to the Lara API.
+    # @param path [String] The path to send the request to.
+    # @param body [Hash,nil] The parameters to send with the request.
+    # @param files [Hash,nil] The files to send with the request. If present, request will be sent as multipart/form-data.
+    # @param headers [Hash,nil] Additional headers to include in the request.
+    # @param raw_response [Boolean] If true, returns the raw response body (useful for binary data like images).
+    # @yield [Hash] Each partial JSON result from the stream (if streaming)
+    # @return [Hash, Array, String, nil] The JSON 'content' from the API, CSV body, or raw bytes.
+    def post(path, body: nil, files: nil, headers: nil, raw_response: false, &callback)
+      request(:post, path, body: body, files: files, headers: headers, raw_response: raw_response, &callback)
+    end
+
+    # Sends a PUT request to the Lara API.
+    # @param path [String] The path to send the request to.
+    # @param body [Hash,nil] The parameters to send with the request.
+    # @param files [Hash,nil] The files to send with the request. If present, request will be sent as multipart/form-data.
+    # @param headers [Hash,nil] Additional headers to include in the request.
+    # @return [Hash, Array, String, nil] The JSON 'content' from the API or CSV body for csv responses.
+    def put(path, body: nil, files: nil, headers: nil)
+      request(:put, path, body: body, files: files, headers: headers)
+    end
+
+    # Sends a DELETE request to the Lara API.
+    # @param path [String] The path to send the request to.
+    # @param params [Hash,nil] The parameters to send with the request.
+    # @param headers [Hash,nil] Additional headers to include in the request.
+    # @return [Hash, Array, String, nil] The JSON 'content' from the API or CSV body for csv responses.
+    def delete(path, params: nil, body: nil, headers: nil)
+      request(:delete, path, body: body, headers: headers, params: params)
+    end
+
+    private
+
+    def request(method, path, body: nil, files: nil, headers: nil, params: nil, raw_response: false, &callback)
+      ensure_valid_token
+
+      make_request(method, path, body: body, files: files, headers: headers, params: params,
+                   raw_response: raw_response, &callback)
+    rescue LaraApiError => e
+      # Auto-refresh token on 401 with jwt expired
+      raise unless e.status_code == 401 && e.message.include?("jwt expired")
+
+      refresh_token
+      # Retry once with new token
+      make_request(method, path, body: body, files: files, headers: headers, params: params,
+                   raw_response: raw_response, &callback)
+    end
+
+    def ensure_valid_token
+      @auth_mutex.synchronize do
+        return if @auth_token
+
+        raise LaraError, "No authentication method available" unless @credentials
+
+        @auth_token = authenticate
+      end
+    end
+
+    def authenticate
+      path = "/v2/auth"
+      method = "POST"
+      timestamp = Time.now.utc.strftime("%a, %d %b %Y %H:%M:%S GMT")
+
+      body = { id: @credentials&.access_key_id }
+      body_json = body.to_json
+      content_md5 = Digest::MD5.hexdigest(body_json)
+
+      headers = {
+        "Date" => timestamp,
+        "X-Lara-SDK-Name" => "lara-ruby",
+        "X-Lara-SDK-Version" => Lara::VERSION,
+        "Content-Type" => "application/json",
+        "Content-MD5" => content_md5,
+        "Authorization" => "Lara:#{generate_hmac_signature(method, path, content_md5,
+                                                           'application/json', timestamp)}"
+      }
+
+      conn = Faraday.new(url: @base_url) do |c|
+        c.adapter Faraday.default_adapter
+      end
+
+      response = conn.post(path) do |req|
+        req.headers = headers
+        req.body = body_json
+      end
+
+      raise LaraApiError.from_response(response) unless response.success?
+
+      data = JSON.parse(response.body)
+      refresh_token = response.headers["x-lara-refresh-token"]
+
+      raise LaraError, "Missing refresh token in authentication response" unless refresh_token
+
+      AuthToken.new(data["token"], refresh_token)
+    end
+
+    def refresh_token
+      @auth_mutex.synchronize do
+        return unless @auth_token
+
+        conn = Faraday.new(url: @base_url) do |c|
+          c.adapter Faraday.default_adapter
+        end
+
+        response = conn.post("/v2/auth/refresh") do |req|
+          req.headers = {
+            "Date" => Time.now.utc.strftime("%a, %d %b %Y %H:%M:%S GMT"),
+            "X-Lara-SDK-Name" => "lara-ruby",
+            "X-Lara-SDK-Version" => Lara::VERSION,
+            "Authorization" => "Bearer #{@auth_token&.refresh_token}"
+          }
+        end
+
+        if response.success?
+          data = JSON.parse(response.body)
+          refresh_token = response.headers["x-lara-refresh-token"]
+
+          if refresh_token
+            @auth_token = AuthToken.new(data["token"], refresh_token)
+          else
+            # Refresh failed, force re-authentication
+            @auth_token = nil
+            ensure_valid_token
+          end
+        else
+          # Refresh failed, force re-authentication
+          @auth_token = nil
+          ensure_valid_token
+        end
+      end
+    end
+
+    def make_request(method, path, body: nil, files: nil, headers: nil, params: nil, raw_response: false, &callback)
+      path = "/#{path}" unless path.start_with?("/")
+      request_headers = build_request_headers(body, files, headers)
+
+      # Make the API call
+      response = if files&.any?
+                   @connection.post(path) do |req|
+                     req.headers.merge!(request_headers)
+                     req.params = params if params
+                     req.body = body.is_a?(Hash) ? body.dup : {}
+                     files.each { |key, value| req.body[key] = value }
+                   end
+                 else
+                   @connection.send(method, path) do |req|
+                     req.headers.merge!(request_headers)
+                     req.params = params if params
+                     req.body = body.to_json if body.is_a?(Hash) && !body.empty?
+                   end
+                 end
+
+      raise LaraApiError.from_response(response) unless response.success?
+
+      return response.body if raw_response
+
+      content_type = response.headers["content-type"] || response.headers["Content-Type"]
+      return response.body if content_type&.include?("text/csv")
+
+      if callback || (body && body[:reasoning])
+        parse_stream_response(response.body, &callback)
+      else
+        parse_json(response.body)
+      end
+    end
+
+    def parse_json(body)
+      parsed = body.nil? || body.empty? ? {} : JSON.parse(body)
+      parsed.is_a?(Hash) && parsed.key?("content") ? parsed["content"] : parsed
+    end
+
+    def parse_stream_response(body, &block)
+      return {} if body.nil? || body.empty?
+
+      buffer = ""
+      last_result = nil
+
+      body.each_line do |line|
+        buffer += line
+        next unless line.end_with?("\n")
+
+        trimmed_line = buffer.strip
+        buffer = ""
+
+        next if trimmed_line.empty?
+
+        begin
+          parsed = JSON.parse(trimmed_line)
+          result = parsed["content"] || parsed
+          block.call(result) if block
+          last_result = result
+        rescue JSON::ParserError
+          next
+        end
+      end
+
+      if !buffer.empty? && buffer.strip != ""
+        begin
+          parsed = JSON.parse(buffer.strip)
+          result = parsed["content"] || parsed
+          block.call(result) if block
+          last_result = result
+        rescue JSON::ParserError
+        end
+      end
+
+      last_result || {}
+    end
+
+    def build_request_headers(body, files, extra_headers)
+      timestamp = Time.now.utc.strftime("%a, %d %b %Y %H:%M:%S GMT")
+
+      headers = {
+        "Date" => timestamp,
+        "X-Lara-SDK-Name" => "lara-ruby",
+        "X-Lara-SDK-Version" => Lara::VERSION,
+        "Authorization" => "Bearer #{@auth_token&.token}",
+        **@extra_headers
+      }
+
+      headers.merge!(extra_headers) if extra_headers
+
+      if !files&.any? && body.is_a?(Hash) && !body.empty?
+        headers["Content-Type"] = "application/json"
+      end
+
+      headers
+    end
+
+    def build_connection
+      Faraday.new(url: @base_url) do |conn|
+        conn.request :multipart
+        conn.request :url_encoded
+        conn.adapter Faraday.default_adapter
+        conn.options.timeout = @connection_timeout if @connection_timeout
+        conn.options.open_timeout = @read_timeout if @read_timeout
+      end
+    end
+
+    def generate_hmac_signature(method, path, content_md5, content_type, timestamp)
+      string_to_sign = [
+        method.to_s.upcase,
+        path,
+        content_md5,
+        content_type,
+        timestamp
+      ].join("\n")
+
+      digest = OpenSSL::HMAC.digest("sha256", @credentials&.access_key_secret || "", string_to_sign)
+      Base64.strict_encode64(digest)
+    end
+  end
+end

data/lib/lara/credentials.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Lara
+  # Credentials for accessing the Lara API. A credentials object has two properties:
+  # - access_key_id: The access key ID.
+  # - access_key_secret: The access key secret.
+
+  # IMPORTANT: Do not hard-code your access key ID and secret in your code. Always use environment variables or
+  # a credentials file. Please note also that the access key secret is never sent directly via HTTP, but it is used to
+  # sign the request. If you suspect that your access key secret has been compromised, you can revoke it in the Lara
+  # dashboard.
+  class Credentials
+    # @!attribute [r] access_key_id
+    #   @return [String] The access key ID.
+    # @!attribute [r] access_key_secret
+    #   @return [String] The access key secret.
+    attr_reader :access_key_id, :access_key_secret
+
+    # @param access_key_id [String] The access key ID.
+    # @param access_key_secret [String] The access key secret.
+    def initialize(access_key_id, access_key_secret)
+      @access_key_id = access_key_id
+      @access_key_secret = access_key_secret
+    end
+  end
+end

data/lib/lara/documents.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Lara
+  class Documents
+    ALLOWED_DOCUMENT_PARAMS = %i[
+      id
+      status
+      target
+      filename
+      source
+      created_at
+      updated_at
+      options
+      translated_chars
+      total_chars
+      error_reason
+    ].freeze
+
+    def initialize(client, s3_client = S3Client.new)
+      @client = client
+      @s3 = s3_client
+      @polling_interval = 2
+    end
+
+    # Uploads a file to S3
+    # @return [Lara::Models::Document]
+    def upload(file_path:, filename:, target:, source: nil, adapt_to: nil, glossaries: nil,
+               no_trace: false, style: nil, password: nil, extraction_params: nil)
+      response_data = @client.get("/v2/documents/upload-url", params: { filename: filename })
+      url = response_data["url"]
+      fields = response_data["fields"]
+
+      @s3.upload(url: url, fields: fields, io: file_path)
+
+      body = {
+        s3key: fields["key"],
+        target: target,
+        source: source,
+        adapt_to: adapt_to,
+        glossaries: glossaries,
+        style: style,
+        password: password,
+        extraction_params: extraction_params&.to_h
+      }.compact
+
+      headers = {}
+      headers["X-No-Trace"] = "true" if no_trace
+
+      response = @client.post("/v2/documents", body: body, headers: headers)
+      response_params = response.transform_keys(&:to_sym)
+      Lara::Models::Document.new(**filter_document_params(response_params))
+    end
+
+    # Fetch document status
+    # @return [Lara::Models::Document]
+    def status(id)
+      response = @client.get("/v2/documents/#{id}")
+      response_params = response.transform_keys(&:to_sym)
+      Lara::Models::Document.new(**filter_document_params(response_params))
+    end
+
+    # Download translated document bytes
+    # @return [String] bytes
+    def download(id, output_format: nil)
+      params = {}
+      params[:output_format] = output_format if output_format
+      url = @client.get("/v2/documents/#{id}/download-url", params: params)["url"]
+      @s3.download(url: url)
+    end
+
+    # Translates a document end-to-end
+    # @return [String] translated file bytes
+    def translate(file_path:, filename:, target:, source: nil, adapt_to: nil, glossaries: nil, output_format: nil,
+                  no_trace: false, style: nil, password: nil, extraction_params: nil)
+      document = upload(file_path: file_path, filename: filename, target: target, source: source,
+                        adapt_to: adapt_to, glossaries: glossaries, no_trace: no_trace, style: style, password: password,
+                        extraction_params: extraction_params)
+
+      max_wait_time = 60 * 15 # 15 minutes
+      start = Time.now
+
+      loop do |_|
+        current = status(document.id)
+
+        case current.status
+        when Lara::Models::DocumentStatus::TRANSLATED
+          return download(current.id, output_format: output_format)
+        when Lara::Models::DocumentStatus::ERROR
+          raise Lara::LaraApiError.new(500, "DocumentError",
+                                       current.error_reason || "Unknown error")
+        end
+
+        raise Timeout::Error if Time.now - start > max_wait_time
+
+        sleep @polling_interval
+      end
+    end
+
+    private
+
+    def filter_document_params(params)
+      params.slice(*ALLOWED_DOCUMENT_PARAMS)
+    end
+  end
+end

data/lib/lara/errors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lara
+  # Base SDK error.
+  class LaraError < StandardError
+    attr_reader :status_code
+
+    def initialize(message, status_code = nil)
+      super(message)
+      @status_code = status_code
+    end
+  end
+
+  # API error with HTTP status, type and message.
+  class LaraApiError < LaraError
+    attr_reader :type
+
+    # Builds an error from an HTTP response with JSON body:
+    # { "error": { "type": "...", "message": "..." } }
+    def self.from_response(response)
+      data = begin
+        JSON.parse(response.body)
+      rescue StandardError
+        {}
+      end
+      error = data["error"] || {}
+      error_type = error["type"] || "UnknownError"
+      error_message = error["message"] || "An unknown error occurred"
+      new(response.status, error_type, error_message)
+    end
+
+    # @param status_code [Integer]
+    # @param type [String]
+    # @param message [String]
+    def initialize(status_code, type, message)
+      super("(HTTP #{status_code}) #{type}: #{message}", status_code)
+      @type = type
+      @message = message
+    end
+  end
+end