answerlayer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a954237e60b4bdd0702fc444f5fbb6c4571785e1ea1a1c3d1195a9f72740ef7
+  data.tar.gz: 68ba2a049a0c86482e0727d73d33cff07d83773b2757c6223f928138fc466db3
+SHA512:
+  metadata.gz: 8bac47e068a61c18255a7b89db7dd922696aba691f99b8c89bb643f5feff04ae9dfc93d39f294b5448c70427f597d4358270417a886543fe57a297d1deb3d999
+  data.tar.gz: a5d2b7f7b9ba225a27337eb87c493f5c79343eb57ea81ac1019ec6e50fb9f1c87ce364f8a8cd1374ccc59a9a36b95b8c3be7c97858c41b654c0eaddb8e3e7060

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Initial AnswerLayer Ruby SDK release.
+- Added `AnswerLayer::Client` with resources for connections, query execution, inquiry sessions, saved queries, dashboards, query results, semantic layer, and identity broker.
+- Added API-key configuration, default AnswerLayer API base URL, request timeouts, subject header support, and OAuth token exchange support.
+- Added JSON request/response handling, downloads, server-sent event parsing, and lightweight response objects: `ApiResponse`, `ResultEnvelope`, `DownloadResponse`, and `StreamEvent`.
+- Added status-aware SDK errors under `AnswerLayer::Error`, including `ApiError` subclasses with `status`, `body`, and `headers`.
+- Added RSpec coverage using captured response fixtures for documented resource shapes.
+- Added public README, resource, response, authentication, configuration, and error documentation.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AnswerLayer Maintainers
+
+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,104 @@
+# AnswerLayer Ruby SDK
+
+The AnswerLayer Ruby SDK is a lightweight client for calling the AnswerLayer API from Ruby applications. It exposes one `AnswerLayer::Client` with resources for connections, query execution, inquiry sessions, saved queries, dashboards, query results, semantic layer, and identity broker.
+
+## Requirements
+
+- Ruby 3.1 or newer
+
+## Installation
+
+With Bundler:
+
+```ruby
+gem "answerlayer"
+```
+
+Then install:
+
+```sh
+bundle install
+```
+
+Or install the gem directly:
+
+```sh
+gem install answerlayer
+```
+
+## Quick Start
+
+Pass your API key directly:
+
+```ruby
+require "answerlayer"
+
+client = AnswerLayer::Client.new(api_key: "your-api-key")
+
+connections = client.connections.list
+
+result = client.query.execute(
+  connection_id: "connection-id",
+  query: "SELECT 1 AS ok"
+)
+```
+
+## Configuration
+
+Pass your API key directly:
+
+```ruby
+client = AnswerLayer::Client.new(api_key: "your-api-key")
+```
+
+See [docs/configuration.md](docs/configuration.md) for timeout, subject header, and advanced configuration options.
+
+## Resources
+
+Resources group related API methods under the client:
+
+```ruby
+client.connections
+client.query
+client.inquiry
+client.saved_queries
+client.dashboards
+client.query_results
+client.semantic
+client.identity_broker
+```
+
+See [docs/resources.md](docs/resources.md) for method-level documentation.
+
+## Responses
+
+The SDK returns plain Ruby hashes/arrays for simple flexible responses and lightweight wrappers for common shapes:
+
+- `AnswerLayer::ApiResponse`
+- `AnswerLayer::ResultEnvelope`
+- `AnswerLayer::DownloadResponse`
+- `AnswerLayer::StreamEvent`
+
+See [docs/responses.md](docs/responses.md).
+
+## Errors
+
+All SDK errors inherit from `AnswerLayer::Error`, so applications can rescue one base class for AnswerLayer failures:
+
+```ruby
+begin
+  client.query.validate(connection_id: "connection-id", query: "SELECT * FROM table")
+rescue AnswerLayer::Error => error
+  warn error.message
+end
+```
+
+HTTP response errors inherit from `AnswerLayer::ApiError` and expose `status`, `body`, and `headers`. Status-specific classes are available for common responses such as bad request, unauthorized, not found, rate limit, and server errors.
+
+See [docs/errors.md](docs/errors.md).
+
+## Examples
+
+Examples under `examples/` show common SDK usage:
+
+- [examples/basic_usage.rb](examples/basic_usage.rb)

data/lib/answerlayer/authentication.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class Authentication
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def apply(headers, mode: :api_key, subject: false)
+      @configuration.validate!(auth_mode: mode)
+      authenticated = headers.dup
+
+      case mode
+      when :api_key, :oauth
+        authenticated["X-API-Key"] = @configuration.api_key
+      when :bearer
+        authenticated["Authorization"] = "Bearer #{@configuration.bearer_token}"
+      when :none
+        authenticated
+      else
+        raise ConfigurationError, "unsupported auth mode: #{mode}"
+      end
+
+      apply_subject_headers(authenticated) if subject && mode != :bearer
+      authenticated
+    end
+
+    private
+      def apply_subject_headers(headers)
+        headers["X-Subject-Org-ID"] = @configuration.subject_org_id if present?(@configuration.subject_org_id)
+        headers["X-Subject-User-ID"] = @configuration.subject_user_id if present?(@configuration.subject_user_id)
+      end
+
+      def present?(value)
+        !value.nil? && !value.to_s.strip.empty?
+      end
+  end
+end

data/lib/answerlayer/client.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class Client
+    DEFAULT_BASE_URL = Configuration::DEFAULT_BASE_URL
+
+    attr_reader :configuration
+
+    def initialize(api_key: nil, bearer_token: nil, subject_org_id: nil, subject_user_id: nil, base_url: DEFAULT_BASE_URL, open_timeout: 10, read_timeout: 30, configuration: nil)
+      @configuration = configuration || Configuration.new(
+        api_key: api_key,
+        bearer_token: bearer_token,
+        subject_org_id: subject_org_id,
+        subject_user_id: subject_user_id,
+        base_url: base_url,
+        open_timeout: open_timeout,
+        read_timeout: read_timeout
+      )
+      @request = Request.new(configuration: @configuration)
+    end
+
+    def get(path, params: nil)
+      request(method: :get, path: path, params: params)
+    end
+
+    def post(path, body: nil)
+      request(method: :post, path: path, body: body)
+    end
+
+    def request(method:, path:, params: nil, body: nil, headers: {}, auth: :api_key, subject: false, form: nil, multipart: nil, download: false)
+      @request.call(method: method, path: path, params: params, body: body, headers: headers, auth: auth, subject: subject, form: form, multipart: multipart, download: download)
+    end
+
+    def connections
+      @connections ||= ConnectionsResource.new(self)
+    end
+
+    def query
+      @query ||= QueryResource.new(self)
+    end
+
+    def inquiry
+      @inquiry ||= InquiryResource.new(self)
+    end
+
+    def saved_queries
+      @saved_queries ||= SavedQueriesResource.new(self)
+    end
+
+    def dashboards
+      @dashboards ||= DashboardsResource.new(self)
+    end
+
+    def query_results
+      @query_results ||= QueryResultsResource.new(self)
+    end
+
+    def semantic
+      @semantic ||= SemanticResource.new(self)
+    end
+
+    def identity_broker
+      @identity_broker ||= IdentityBrokerResource.new(self)
+    end
+  end
+end

data/lib/answerlayer/configuration.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class Configuration
+    DEFAULT_BASE_URL = "https://app.answerlayer.io/api/v1"
+
+    attr_accessor :api_key, :bearer_token, :subject_org_id, :subject_user_id, :base_url, :open_timeout, :read_timeout
+
+    def initialize(api_key: nil, bearer_token: nil, subject_org_id: nil, subject_user_id: nil, base_url: nil, open_timeout: 10, read_timeout: 30)
+      @api_key = explicit_or_env(api_key, "ANSWERLAYER_API_KEY")
+      @bearer_token = explicit_or_env(bearer_token, "ANSWERLAYER_BEARER_TOKEN")
+      @subject_org_id = subject_org_id
+      @subject_user_id = subject_user_id
+      @base_url = base_url || DEFAULT_BASE_URL
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    def validate!(auth_mode: :api_key)
+      raise ConfigurationError, "base_url is required" if blank?(base_url)
+      case auth_mode
+      when :api_key, :oauth
+        raise ConfigurationError, "api_key is required" if blank?(api_key)
+      when :bearer
+        raise ConfigurationError, "bearer_token is required" if blank?(bearer_token)
+      when :none
+        true
+      else
+        raise ConfigurationError, "unsupported auth mode: #{auth_mode}"
+      end
+
+      self
+    end
+
+    def base_uri
+      URI(base_url)
+    rescue URI::InvalidURIError
+      raise ConfigurationError, "base_url must be a valid URL"
+    end
+
+    private
+      def explicit_or_env(value, env_key)
+        return value unless blank?(value)
+
+        ENV[env_key]
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+  end
+end

data/lib/answerlayer/errors.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class Error < StandardError; end
+
+  # Local SDK errors.
+  class ConfigurationError < Error; end
+
+  class RequestError < Error; end
+
+  class ResponseError < Error; end
+
+  # HTTP API errors.
+  class ApiError < Error
+    attr_reader :status, :body, :headers
+
+    def initialize(message, status:, body: nil, headers: nil)
+      @status = status
+      @body = body
+      @headers = headers
+      super(message)
+    end
+  end
+
+  class BadRequestError < ApiError; end
+
+  class UnauthorizedError < ApiError; end
+
+  class ForbiddenError < ApiError; end
+
+  class NotFoundError < ApiError; end
+
+  class ConflictError < ApiError; end
+
+  class GoneError < ApiError; end
+
+  class UnprocessableEntityError < ApiError; end
+
+  class RateLimitError < ApiError; end
+
+  class ServerError < ApiError; end
+
+  # OAuth-shaped API errors.
+  class OAuthError < ApiError
+    attr_reader :error, :error_description
+
+    def initialize(message, error: nil, error_description: nil, status: nil, body: nil, headers: nil)
+      @error = error
+      @error_description = error_description
+      super(message, status: status, body: body, headers: headers)
+    end
+  end
+
+  # Server-sent event stream errors.
+  class StreamError < Error
+    attr_reader :event
+
+    def initialize(message, event: nil)
+      @event = event
+      super(message)
+    end
+  end
+end

data/lib/answerlayer/request.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module AnswerLayer
+  class Request
+    DEFAULT_HEADERS = {
+      "Accept" => "application/json",
+      "Content-Type" => "application/json"
+    }.freeze
+
+    def initialize(configuration:, authentication: Authentication.new(configuration))
+      @configuration = configuration
+      @authentication = authentication
+    end
+
+    FORM_HEADERS = {
+      "Accept" => "application/json",
+      "Content-Type" => "application/x-www-form-urlencoded"
+    }.freeze
+
+    MULTIPART_HEADERS = {
+      "Accept" => "application/json",
+      "Content-Type" => "multipart/form-data"
+    }.freeze
+
+    def call(method:, path:, params: nil, body: nil, headers: {}, auth: :api_key, subject: false, form: nil, multipart: nil, download: false)
+      uri = build_uri(path, params)
+      request = build_request(method, uri, body, headers: headers, auth: auth, subject: subject, form: form, multipart: multipart)
+      response = perform(uri, request)
+      parsed_response(response, download: download)
+    rescue Timeout::Error, Errno::ECONNREFUSED, SocketError => error
+      raise RequestError, "request failed: #{error.message}"
+    end
+
+    private
+      def build_uri(path, params)
+        base = @configuration.base_uri
+        uri = base.dup
+        request_path = path.to_s.sub(%r{\A/}, "")
+        uri.path = if path.to_s.start_with?("/.well-known")
+          path.to_s
+        else
+          base_path = base.path.to_s.sub(%r{/\z}, "")
+          [base_path, request_path].reject(&:empty?).join("/")
+        end
+        uri.query = URI.encode_www_form(params) if params && !params.empty?
+        uri
+      end
+
+      def build_request(method, uri, body, headers:, auth:, subject:, form:, multipart:)
+        request_class = request_class_for(method)
+        request = request_class.new(uri)
+        base_headers = if form
+          FORM_HEADERS
+        elsif multipart
+          MULTIPART_HEADERS
+        else
+          DEFAULT_HEADERS
+        end
+        @authentication.apply(base_headers.merge(headers), mode: auth, subject: subject).each { |key, value| request[key] = value }
+        request.body = URI.encode_www_form(form) if form
+        request.body = multipart.inspect if multipart
+        request.body = JSON.generate(body) unless body.nil? || form
+        request
+      end
+
+      def request_class_for(method)
+        case method.to_s.downcase
+        when "get" then Net::HTTP::Get
+        when "post" then Net::HTTP::Post
+        when "put" then Net::HTTP::Put
+        when "patch" then Net::HTTP::Patch
+        when "delete" then Net::HTTP::Delete
+        else
+          raise RequestError, "unsupported HTTP method: #{method}"
+        end
+      end
+
+      def perform(uri, request)
+        Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", open_timeout: @configuration.open_timeout, read_timeout: @configuration.read_timeout) do |http|
+          http.request(request)
+        end
+      end
+
+      def parsed_response(raw_response, download:)
+        response = Response.new(status: raw_response.code, headers: raw_response.to_hash, body: raw_response.body)
+        raise_error_for(response) unless response.success?
+        return download_response(response) if download && !response.json?
+
+        response.parsed_body
+      end
+
+      def download_response(response)
+        DownloadResponse.new(
+          body: response.body,
+          content_type: Array(response.headers["content-type"]).first,
+          filename: filename_from(response.headers),
+          status: response.status,
+          headers: response.headers
+        )
+      end
+
+      def filename_from(headers)
+        disposition = Array(headers["content-disposition"]).first
+        disposition&.match(/filename="?([^";]+)"?/) { |match| match[1] }
+      end
+
+      def raise_error_for(response)
+        parsed = response.json? ? safe_parse(response) : nil
+        message = parsed && (parsed["detail"] || parsed["error_description"] || parsed["error"])
+        message ||= "request failed with status #{response.status}"
+
+        if parsed && parsed["error"]
+          raise OAuthError.new(message, error: parsed["error"], error_description: parsed["error_description"], status: response.status, body: response.body, headers: response.headers)
+        end
+
+        error_class = case response.status
+        when 400 then BadRequestError
+        when 401 then UnauthorizedError
+        when 403 then ForbiddenError
+        when 404 then NotFoundError
+        when 409 then ConflictError
+        when 410 then GoneError
+        when 422 then UnprocessableEntityError
+        when 429 then RateLimitError
+        when 500..599 then ServerError
+        else RequestError
+        end
+
+        raise RequestError, message if error_class == RequestError
+
+        raise error_class.new(message, status: response.status, body: response.body, headers: response.headers)
+      end
+
+      def safe_parse(response)
+        response.parsed_body
+      rescue ResponseError
+        nil
+      end
+  end
+end

data/lib/answerlayer/resources/base.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class Resource
+    def initialize(client)
+      @client = client
+    end
+
+    private
+      def request(**kwargs)
+        @client.request(**kwargs)
+      end
+
+      def to_api_response(data)
+        data.is_a?(ApiResponse) ? data : ApiResponse.new(data || {})
+      end
+
+      def to_result_envelope(data)
+        data.is_a?(ResultEnvelope) ? data : ResultEnvelope.new(data || {})
+      end
+
+      def compact(hash)
+        hash.reject { |_key, value| value.nil? }
+      end
+  end
+end

data/lib/answerlayer/resources/connections.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class ConnectionsResource < Resource
+    def list
+      request(method: :get, path: "/connections/")
+    end
+
+    def test_existing(connection_id:)
+      to_api_response(request(method: :post, path: "/connections/#{connection_id}/test_existing"))
+    end
+
+    def schema(connection_id:)
+      request(method: :get, path: "/connections/#{connection_id}/schema")
+    end
+
+    def upload_csv(file:, name: nil, has_header: nil, delimiter: nil)
+      request(method: :post, path: "/csv/upload", multipart: compact(file: file, name: name, has_header: has_header, delimiter: delimiter))
+    end
+
+    def upload_duckdb(file:, name: nil)
+      request(method: :post, path: "/duckdb/upload", multipart: compact(file: file, name: name))
+    end
+  end
+end

data/lib/answerlayer/resources/dashboards.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class DashboardsResource < Resource
+    def manifest(dashboard_id:)
+      request(method: :get, path: "/dashboards/#{dashboard_id}/manifest", subject: true)
+    end
+
+    def tile_data(dashboard_id:, tile_id:, filters: nil, params: nil, pagination: nil, result_handle: nil)
+      to_result_envelope(request(method: :post, path: "/dashboards/#{dashboard_id}/tiles/#{tile_id}/data", body: compact(filters: filters, params: params, pagination: pagination, result_handle: result_handle), subject: true))
+    end
+
+    def parameters(dashboard_id:, tile_id:)
+      to_api_response(request(method: :get, path: "/dashboards/#{dashboard_id}/tiles/#{tile_id}/parameters", subject: true))
+    end
+
+    def update_parameters(dashboard_id:, tile_id:, values:, subject_org_id: nil)
+      headers = subject_org_id ? { "X-Subject-Org-ID" => subject_org_id } : {}
+      to_api_response(request(method: :put, path: "/dashboards/#{dashboard_id}/tiles/#{tile_id}/parameters", body: { values: values }, headers: headers, subject: true))
+    end
+  end
+end

data/lib/answerlayer/resources/identity_broker.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class IdentityBrokerResource < Resource
+    SUBJECT_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:jwt"
+
+    def exchange_token(subject_token:, subject_token_type: SUBJECT_TOKEN_TYPE)
+      to_api_response(request(method: :post, path: "/oauth/token", auth: :oauth, form: {
+        grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+        subject_token: subject_token,
+        subject_token_type: subject_token_type
+      }))
+    end
+
+    def jwks
+      to_api_response(request(method: :get, path: "/.well-known/jwks.json", auth: :none))
+    end
+  end
+end

data/lib/answerlayer/resources/inquiry.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class InquiryResource < Resource
+    def create_session(connection_id:, model: nil)
+      to_api_response(request(method: :post, path: "/inquiry/sessions", body: compact(connection_id: connection_id, model: model)))
+    end
+
+    def list_sessions
+      request(method: :get, path: "/inquiry/sessions")
+    end
+
+    def session(session_id:)
+      request(method: :get, path: "/inquiry/sessions/#{session_id}")
+    end
+
+    def turn_stream(session_id:, user_input:)
+      request(method: :post, path: "/inquiry/sessions/#{session_id}", body: { user_input: user_input })
+    end
+
+    def turn_sync(session_id:, user_input:)
+      to_api_response(request(method: :post, path: "/inquiry/sessions/#{session_id}/sync", body: { user_input: user_input }))
+    end
+  end
+end

data/lib/answerlayer/resources/query.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class QueryResource < Resource
+    def execute(connection_id:, query:, params: nil, row_limit: nil, timeout: nil)
+      request(method: :post, path: "/query/#{connection_id}", body: compact(query: query, params: params, row_limit: row_limit, timeout: timeout))
+    end
+
+    def validate(connection_id:, query:)
+      to_api_response(request(method: :post, path: "/query/#{connection_id}/validate", body: { query: query }))
+    end
+
+    def export(connection_id:, query:, format: :csv, params: nil, row_limit: nil, timeout: nil)
+      request(
+        method: :post,
+        path: "/query/#{connection_id}/export",
+        params: { format: format },
+        body: compact(query: query, params: params, row_limit: row_limit, timeout: timeout),
+        download: true
+      )
+    end
+  end
+end

data/lib/answerlayer/resources/query_results.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class QueryResultsResource < Resource
+    def get(handle:, cursor: nil, limit: nil)
+      to_result_envelope(request(method: :get, path: "/query-results/#{handle}", params: compact(cursor: cursor, limit: limit)))
+    end
+
+    def release(handle:)
+      request(method: :delete, path: "/query-results/#{handle}")
+    end
+  end
+end

data/lib/answerlayer/resources/saved_queries.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class SavedQueriesResource < Resource
+    def list
+      to_api_response(request(method: :get, path: "/saved-queries"))
+    end
+
+    def create(name:, sql:, connection_id:, description: nil, visibility: nil)
+      to_api_response(request(method: :post, path: "/saved-queries", body: compact(name: name, sql: sql, connection_id: connection_id, description: description, visibility: visibility)))
+    end
+
+    def get(saved_query_id:)
+      to_api_response(request(method: :get, path: "/saved-queries/#{saved_query_id}"))
+    end
+
+    def execute(saved_query_id:, params: nil, row_limit: nil, timeout: nil)
+      to_result_envelope(request(method: :post, path: "/saved-queries/#{saved_query_id}/execute", body: compact(params: params, row_limit: row_limit, timeout: timeout)))
+    end
+
+    def update(saved_query_id:, **attributes)
+      to_api_response(request(method: :patch, path: "/saved-queries/#{saved_query_id}", body: attributes))
+    end
+
+    def delete(saved_query_id:)
+      request(method: :delete, path: "/saved-queries/#{saved_query_id}")
+    end
+
+    def create_from_inquiry_turn(inquiry_turn_id:, name:, description: nil, visibility: nil)
+      to_api_response(request(method: :post, path: "/saved-queries/from-inquiry-turn", body: compact(inquiry_turn_id: inquiry_turn_id, name: name, description: description, visibility: visibility)))
+    end
+  end
+end

data/lib/answerlayer/resources/semantic.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class SemanticResource < Resource
+    def components(component:, connection_id:)
+      to_api_response(request(method: :get, path: "/semantic/#{component}", params: { connection_id: connection_id }))
+    end
+
+    def jobs
+      to_api_response(request(method: :get, path: "/semantic/jobs"))
+    end
+
+    def create_component(component:, attributes:)
+      to_api_response(request(method: :post, path: "/semantic/#{component}", body: attributes))
+    end
+
+    def get_component(component:, id:)
+      to_api_response(request(method: :get, path: "/semantic/#{component}/#{id}"))
+    end
+
+    def update_component(component:, id:, attributes:)
+      to_api_response(request(method: :put, path: "/semantic/#{component}/#{id}", body: attributes))
+    end
+
+    def delete_component(component:, id:)
+      request(method: :delete, path: "/semantic/#{component}/#{id}")
+    end
+
+    def generate_stream(component:, connection_id:, prompt: nil)
+      request(method: :post, path: "/semantic/#{component}/generate/stream", body: compact(connection_id: connection_id, prompt: prompt))
+    end
+
+    def create_job(connection_id:, component_type:, prompt: nil)
+      to_api_response(request(method: :post, path: "/semantic/jobs", body: compact(connection_id: connection_id, component_type: component_type, prompt: prompt)))
+    end
+
+    def job_stream(job_id:)
+      request(method: :get, path: "/semantic/jobs/#{job_id}/stream")
+    end
+
+    def job_questions(job_id:)
+      to_api_response(request(method: :get, path: "/semantic/jobs/#{job_id}/questions"))
+    end
+
+    def submit_guidance(job_id:, responses:)
+      to_api_response(request(method: :post, path: "/semantic/jobs/#{job_id}/guidance", body: { responses: responses }))
+    end
+
+    def job_status(job_id:)
+      to_api_response(request(method: :get, path: "/semantic/jobs/#{job_id}/status"))
+    end
+
+    def cancel_job(job_id:)
+      to_api_response(request(method: :post, path: "/semantic/jobs/#{job_id}/cancel"))
+    end
+  end
+end

data/lib/answerlayer/responses/api_response.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class ApiResponse
+    attr_reader :data, :status, :headers
+
+    def initialize(data = {}, status: nil, headers: {})
+      @data = data
+      @status = status
+      @headers = headers
+    end
+
+    def [](key)
+      data[key.to_s] || data[key.to_sym]
+    end
+
+    def to_h
+      data
+    end
+  end
+end

data/lib/answerlayer/responses/download_response.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class DownloadResponse
+    attr_reader :body, :content_type, :filename, :status, :headers
+
+    def initialize(body:, content_type: nil, filename: nil, status: nil, headers: {})
+      @body = body
+      @content_type = content_type
+      @filename = filename
+      @status = status
+      @headers = headers
+    end
+  end
+end

data/lib/answerlayer/responses/response.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AnswerLayer
+  class Response
+    attr_reader :status, :headers, :body
+
+    def initialize(status:, headers:, body:)
+      @status = status.to_i
+      @headers = headers
+      @body = body
+    end
+
+    def success?
+      status.between?(200, 299)
+    end
+
+    def json?
+      content_type = Array(headers["content-type"] || headers["Content-Type"]).join(";")
+      content_type.include?("json") || body.to_s.strip.start_with?("{", "[")
+    end
+
+    def parsed_body
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => error
+      raise ResponseError, "response body was not valid JSON: #{error.message}"
+    end
+  end
+end

data/lib/answerlayer/responses/result_envelope.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class ResultEnvelope < ApiResponse
+    def columns
+      self["columns"] || []
+    end
+
+    def rows
+      self["rows"] || []
+    end
+
+    def next_cursor
+      self["next_cursor"]
+    end
+
+    def result_handle
+      self["result_handle"]
+    end
+
+    def has_next_page?
+      !next_cursor.nil? && !next_cursor.to_s.empty?
+    end
+  end
+end

data/lib/answerlayer/responses/sse_parser.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AnswerLayer
+  class SSEParser
+    def self.parse(stream)
+      events = []
+      current_type = "message"
+      data_lines = []
+
+      stream.each_line do |line|
+        line = line.chomp
+        if line.empty?
+          events << build_event(current_type, data_lines.join("\n")) unless data_lines.empty?
+          current_type = "message"
+          data_lines = []
+          next
+        end
+
+        field, value = line.split(":", 2)
+        value = value ? value.sub(/\A /, "") : ""
+        case field
+        when "event"
+          current_type = value
+        when "data"
+          data_lines << value
+        end
+      end
+
+      events << build_event(current_type, data_lines.join("\n")) unless data_lines.empty?
+      events
+    end
+
+    def self.build_event(type, raw_data)
+      data = JSON.parse(raw_data)
+      event = StreamEvent.new(type: type, data: data, raw: raw_data)
+      raise StreamError.new(data["message"] || data["error"] || "stream error", event: event) if event.error?
+
+      event
+    rescue JSON::ParserError
+      StreamEvent.new(type: type, data: raw_data, raw: raw_data)
+    end
+  end
+end

data/lib/answerlayer/responses/stream_event.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  class StreamEvent
+    attr_reader :type, :data, :raw
+
+    def initialize(type:, data:, raw: nil)
+      @type = type.to_s
+      @data = data
+      @raw = raw
+    end
+
+    def error?
+      type == "error"
+    end
+  end
+end

data/lib/answerlayer/responses.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "responses/response"
+require_relative "responses/api_response"
+require_relative "responses/result_envelope"
+require_relative "responses/download_response"
+require_relative "responses/stream_event"
+require_relative "responses/sse_parser"

data/lib/answerlayer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AnswerLayer
+  VERSION = "0.1.0"
+end

data/lib/answerlayer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "answerlayer/version"
+require_relative "answerlayer/errors"
+require_relative "answerlayer/configuration"
+require_relative "answerlayer/authentication"
+require_relative "answerlayer/responses"
+require_relative "answerlayer/request"
+require_relative "answerlayer/resources/base"
+require_relative "answerlayer/resources/connections"
+require_relative "answerlayer/resources/query"
+require_relative "answerlayer/resources/inquiry"
+require_relative "answerlayer/resources/saved_queries"
+require_relative "answerlayer/resources/dashboards"
+require_relative "answerlayer/resources/query_results"
+require_relative "answerlayer/resources/semantic"
+require_relative "answerlayer/resources/identity_broker"
+require_relative "answerlayer/client"
+
+module AnswerLayer
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      configuration
+    end
+
+    def client
+      Client.new(configuration: configuration)
+    end
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: answerlayer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- AnswerLayer Maintainers
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: A dependency-light Ruby client for AnswerLayer connections, queries,
+  inquiry sessions, saved queries, dashboards, query results, semantic-layer APIs,
+  and identity broker APIs.
+email:
+- maintainers@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/answerlayer.rb
+- lib/answerlayer/authentication.rb
+- lib/answerlayer/client.rb
+- lib/answerlayer/configuration.rb
+- lib/answerlayer/errors.rb
+- lib/answerlayer/request.rb
+- lib/answerlayer/resources/base.rb
+- lib/answerlayer/resources/connections.rb
+- lib/answerlayer/resources/dashboards.rb
+- lib/answerlayer/resources/identity_broker.rb
+- lib/answerlayer/resources/inquiry.rb
+- lib/answerlayer/resources/query.rb
+- lib/answerlayer/resources/query_results.rb
+- lib/answerlayer/resources/saved_queries.rb
+- lib/answerlayer/resources/semantic.rb
+- lib/answerlayer/responses.rb
+- lib/answerlayer/responses/api_response.rb
+- lib/answerlayer/responses/download_response.rb
+- lib/answerlayer/responses/response.rb
+- lib/answerlayer/responses/result_envelope.rb
+- lib/answerlayer/responses/sse_parser.rb
+- lib/answerlayer/responses/stream_event.rb
+- lib/answerlayer/version.rb
+homepage: https://github.com/ironguild/answerlayer-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ironguild/answerlayer-ruby
+  source_code_uri: https://github.com/ironguild/answerlayer-ruby
+  changelog_uri: https://github.com/ironguild/answerlayer-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby API wrapper for the AnswerLayer API.
+test_files: []