intosql 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b676b287df23b8fe20bbcb97825e67771ac377d15b0bb92aeb74852c4e9e5dbe
+  data.tar.gz: 7486228ea1d9f8b5908c7b5d8a398f5a2c60d621d5984b13e6ac3af964fc552e
+SHA512:
+  metadata.gz: 3397f1e8a866a81eb52e64c6db766df8709f49b0fc3cab1b6cafef0b0f076df9e9e0b8c9f0b5a5a689c4aa18df3bc82d64383db7bdeff12363b928dcb7898494
+  data.tar.gz: 932b8af6b15e7ffab77f9f65ade11449eee62cfc553d36e7b8b1812115b61d1ad023210479e693d331ae803b950c192868c7341f23b4c891e19e032ac8cf9761

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- `convert` and `convert_url`, every conversion endpoint (`create`, `create_from_url`, `upload`, `start`, `retrieve`, `list`, `cancel`, `create_case`, `delete`, `wait`), `usage` and `spec`.
+- `verify_webhook` and `parse_webhook`, which returns a typed `WebhookEvent`.
+- `APIError` with `status`, `code`, `fields` and `request_id`; `ConversionFailedError`, `ConversionCanceledError` and `TimeoutError`.
+- Retries for rate limits, a full account, server errors and lost connections, with the same idempotency key; never `already_started`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IntoSQL
+
+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,51 @@
+# IntoSQL for Ruby
+
+Convert spreadsheets (XLSX, XLS, ODS), CSV and JSON into SQL for PostgreSQL, MySQL, MariaDB, SQLite, SQL Server or Oracle with the [IntoSQL API](https://intosql.com/developers). Column types are inferred and dirty values fixed, so the script loads on the first try.
+
+```sh
+gem install intosql
+```
+
+Ruby 3.1 or newer, no dependencies beyond the standard library. The API is part of IntoSQL Pro; make a key in Settings, API keys.
+
+## Convert a file
+
+```ruby
+require "intosql"
+
+intosql = IntoSQL::Client.new(api_key: ENV.fetch("INTOSQL_API_KEY"))
+
+conversion = intosql.convert("ventas.xlsx", spec: IntoSQL.spec(dialect: "postgresql", table: "ventas"))
+
+puts conversion.report[:rows][:converted], conversion.output.url
+```
+
+The file streams to storage as it is; the output URL downloads the script for ten minutes. Read the conversion again (`intosql.conversions.retrieve(id)`) for a fresh one.
+
+## Convert a file by URL
+
+```ruby
+conversion = intosql.convert_url(
+  "https://example.com/exports/ventas.csv",
+  spec: IntoSQL.spec(dialect: "mysql")
+)
+```
+
+## Check a webhook
+
+Save a webhook address in Settings, API keys, and IntoSQL calls it when a conversion is done, failed or canceled.
+
+```ruby
+# Raises IntoSQL::SignatureError when the signature doesn't match.
+event = IntoSQL.parse_webhook(
+  request.raw_post,
+  request.headers["IntoSQL-Signature"].to_s,
+  ENV.fetch("INTOSQL_WEBHOOK_SECRET")
+)
+```
+
+## Errors and retries
+
+Failed requests raise `IntoSQL::APIError` with the HTTP `status`, a `code` that doesn't change (`needs_pro`, `over_quota`, `too_big`, `invalid_spec`, `invalid_url` and more) and the `request_id`. A conversion that ends as failed raises `IntoSQL::ConversionFailedError` with its `code` and the engine's `problems`. Rate limits, a full account, server errors and lost connections are retried twice with the same idempotency key (`max_retries:` changes it); `already_started` never is.
+
+Every endpoint: [intosql.com/developers](https://intosql.com/developers).

data/lib/intosql/client.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "uri"
+
+module IntoSQL
+  # The IntoSQL API: convert spreadsheets, CSV and JSON into SQL on IntoSQL's machines.
+  class Client
+    DEFAULT_BASE_URL = "https://intosql.com/api/v1"
+
+    # Codes worth sending again: waiting fixes them. Never `already_started`, which means it is on its way.
+    RETRYABLE_CODES = %w[rate_limited too_many_active request_in_progress].freeze
+
+    # Statuses from the network in between (gateways, timeouts), which carry no code of ours.
+    RETRYABLE_STATUSES = [408, 425, 502, 503, 504].freeze
+
+    attr_reader :conversions
+
+    # `max_retries`: attempts after the first one for rate limits, a full account, server errors
+    # and lost connections. `timeout`: seconds per request for the default transport.
+    # `transport`, `sleeper` and `clock` replace the network, `sleep` and the monotonic clock.
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, max_retries: 2, timeout: 60, transport: nil,
+                   sleeper: nil, clock: nil)
+      raise ArgumentError, "An API key is required: make one in Settings, API keys." if api_key.to_s.empty?
+
+      @api_key = api_key
+      @base_url = base_url.chomp("/")
+      @max_retries = max_retries
+      @transport = transport || NetHTTPTransport.new(timeout: timeout)
+      @sleeper = sleeper || ->(seconds) { Kernel.sleep(seconds) }
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @conversions = Conversions.new(self)
+    end
+
+    # Uploads `file` (a path, or an IO with `bytes:` when it has no `size`), converts it and waits
+    # for the result. `name` defaults to the file's base name.
+    def convert(file, spec:, name: nil, bytes: nil, timeout: Conversions::WAIT_TIMEOUT, interval: nil)
+      opened = Source.open(file, bytes: bytes, name: name) do |source|
+        raise ArgumentError, "Pass name: so IntoSQL can tell the file's format." if source.name.nil?
+
+        conversion = conversions.create(name: source.name, bytes: source.bytes, spec: spec)
+        conversions.upload(conversion, source.io, bytes: source.bytes)
+        conversion
+      end
+
+      conversions.start(opened.id)
+      conversions.wait(opened.id, timeout: timeout, interval: interval)
+    end
+
+    # Converts the file at a public HTTPS address and waits for the result.
+    def convert_url(url, spec:, name: nil, timeout: Conversions::WAIT_TIMEOUT, interval: nil)
+      queued = conversions.create_from_url(url: url, spec: spec, name: name)
+
+      conversions.wait(queued.id, timeout: timeout, interval: interval)
+    end
+
+    # Bytes of conversions the plan includes this month, used and left.
+    def usage
+      Usage.from_h(request("GET", "/usage").fetch(:data))
+    end
+
+    # @api private
+    def request(method, path, body = nil)
+      url = resolve(path)
+      headers = headers_for(method, body)
+      payload = body && JSON.generate(body)
+      attempt = 0
+
+      loop do
+        response = send_once(method, url, headers, payload, attempt)
+
+        if response.nil?
+          attempt += 1
+          next
+        end
+
+        return parse(response) if response.success?
+
+        error = to_error(response)
+        raise error unless retryable?(error) && attempt < @max_retries
+
+        pause(backoff(attempt, response.header("retry-after")))
+        attempt += 1
+      end
+    end
+
+    # @api private
+    def transport_call(**request)
+      @transport.call(**request)
+    end
+
+    # @api private
+    def pause(seconds)
+      @sleeper.call(seconds)
+    end
+
+    # @api private
+    def now
+      @clock.call
+    end
+
+    private
+
+    # The response, or nil when the connection failed and another attempt is due.
+    def send_once(method, url, headers, payload, attempt)
+      @transport.call(method: method, url: url, headers: headers, body: payload)
+    rescue ConnectionError
+      raise if attempt >= @max_retries
+
+      pause(backoff(attempt, nil))
+      nil
+    end
+
+    def headers_for(method, body)
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => "intosql-ruby/#{VERSION}"
+      }
+      headers["Content-Type"] = "application/json" unless body.nil?
+      headers["Idempotency-Key"] = SecureRandom.uuid if method == "POST"
+      headers
+    end
+
+    def parse(response)
+      response.status == 204 ? nil : JSON.parse(response.body, symbolize_names: true)
+    end
+
+    # A path under the API, or one of its own absolute addresses (pagination links).
+    def resolve(path)
+      return "#{@base_url}#{path}" unless path.start_with?("http")
+
+      origin = origin_of(path)
+      raise Error, "Refusing to send the API key to #{origin}." unless origin == origin_of(@base_url)
+
+      path
+    end
+
+    def origin_of(url)
+      uri = URI(url)
+      port = uri.port == uri.default_port ? "" : ":#{uri.port}"
+
+      "#{uri.scheme}://#{uri.host}#{port}"
+    end
+
+    def to_error(response)
+      error = error_body(response)
+
+      APIError.new(
+        response.status,
+        error[:code] || "http_error",
+        error[:message] || "The API answered #{response.status}.",
+        error[:fields] || {},
+        error[:request_id] || response.header("x-request-id")
+      )
+    end
+
+    # The answer's `error` object, or an empty hash when it has none.
+    def error_body(response)
+      body = JSON.parse(response.body, symbolize_names: true)
+      body.is_a?(Hash) && body[:error].is_a?(Hash) ? body[:error] : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def retryable?(error)
+      RETRYABLE_CODES.include?(error.code) || RETRYABLE_STATUSES.include?(error.status) || error.status >= 500
+    end
+
+    def backoff(attempt, retry_after)
+      seconds = Float(retry_after, exception: false)
+
+      return seconds if seconds&.finite? && seconds.positive?
+
+      [0.5 * (2**attempt), 8.0].min
+    end
+  end
+end

data/lib/intosql/conversions.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module IntoSQL
+  # Each step of a conversion on its own, for uploading from somewhere else, starting later, or
+  # not waiting. Reach it as `client.conversions`.
+  class Conversions
+    # Seconds `wait` keeps reading before it gives up: one hour.
+    WAIT_TIMEOUT = 3600
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Opens a conversion; the answer has the address to upload the file to.
+    def create(name:, bytes:, spec:)
+      conversion("POST", "/conversions", { name: name, bytes: bytes, spec: spec })
+    end
+
+    # Queues a conversion of the file at a public HTTPS address.
+    def create_from_url(url:, spec:, name: nil)
+      conversion("POST", "/conversions", { url: url, spec: spec, name: name }.compact)
+    end
+
+    # Sends the file to the address `create` answered with, streamed as it is. Not retried: a
+    # failed upload raises APIError with code `upload_failed`.
+    def upload(conversion, file, bytes: nil)
+      target = conversion.upload
+      raise Error, "Conversion #{conversion.id} has no upload address: open it with create." if target.nil?
+
+      Source.open(file, bytes: bytes) { |source| put(target, source) }
+
+      nil
+    end
+
+    # Starts a conversion once its file is uploaded whole.
+    def start(id)
+      conversion("POST", "#{path(id)}/start")
+    end
+
+    def retrieve(id)
+      conversion("GET", path(id))
+    end
+
+    # Every conversion, newest first, as a lazy Enumerator that fetches a page at a time and
+    # follows `links.next`; `status` keeps only those in it.
+    def list(limit: nil, status: nil)
+      query = URI.encode_www_form({ limit: limit, status: status }.compact)
+      first = query.empty? ? "/conversions" : "/conversions?#{query}"
+
+      Enumerator.new do |yielder|
+        address = first
+
+        until address.nil?
+          page = Page.from_h(@client.request("GET", address)) { |item| Conversion.from_h(item) }
+          page.data.each { |item| yielder << item }
+          address = page.links[:next]
+        end
+      end
+    end
+
+    # Stops a conversion that hasn't ended; canceling it again answers the same.
+    def cancel(id)
+      conversion("POST", "#{path(id)}/cancel")
+    end
+
+    # Sends a conversion that didn't come out right to IntoSQL, so support for it gets added.
+    # `consent` must be true: the person agrees to send it. `share: "file"` sends the file too.
+    def create_case(id, consent:, share: nil, email: nil, note: nil)
+      raise ArgumentError, "consent must be true: the person agrees to send it." unless consent == true
+
+      body = { consent: true, share: share, email: email, note: note }.compact
+
+      Case.from_h(@client.request("POST", "#{path(id)}/cases", body).fetch(:data))
+    end
+
+    # Deletes its files now instead of after 24 hours.
+    def delete(id)
+      @client.request("DELETE", path(id))
+
+      nil
+    end
+
+    # Reads the conversion until it is done; raises ConversionFailedError if it fails,
+    # ConversionCanceledError if it is canceled and TimeoutError after `timeout` seconds. Pauses
+    # grow from half a second to 5 seconds, or are `interval` seconds when given.
+    def wait(id, timeout: WAIT_TIMEOUT, interval: nil)
+      deadline = @client.now + timeout
+      attempt = 0
+
+      loop do
+        conversion = retrieve(id)
+        return conversion if ended?(conversion)
+        raise TimeoutError.new(id, conversion.status) if @client.now >= deadline
+
+        @client.pause(interval || [0.5 * (2**attempt), 5.0].min)
+        attempt += 1
+      end
+    end
+
+    private
+
+    # True when done; raises when failed or canceled; false while it is still on its way.
+    def ended?(conversion)
+      case conversion.status
+      when ConversionStatus::DONE then true
+      when ConversionStatus::FAILED then raise ConversionFailedError.new(conversion.id, conversion.error)
+      when ConversionStatus::CANCELED then raise ConversionCanceledError, conversion.id
+      else false
+      end
+    end
+
+    def put(target, source)
+      response = @client.transport_call(
+        method: "PUT", url: target.url, headers: upload_headers(target, source), body: source.io
+      )
+      return if response.success?
+
+      raise APIError.new(response.status, "upload_failed", "The upload answered #{response.status}.")
+    end
+
+    def conversion(method, address, body = nil)
+      Conversion.from_h(@client.request(method, address, body).fetch(:data))
+    end
+
+    def path(id)
+      "/conversions/#{escape(id)}"
+    end
+
+    # The same as JavaScript's encodeURIComponent.
+    def escape(id)
+      id.to_s.b.gsub(/[^A-Za-z0-9\-_.!~*'()]/n) { |char| format("%%%02X", char.ord) }
+    end
+
+    def upload_headers(target, source)
+      headers = target.headers.to_h { |name, value| [name.to_s, Array(value).join(", ")] }
+      names = headers.keys.map(&:downcase)
+      headers["Content-Length"] = source.bytes.to_s unless names.include?("content-length")
+      headers["Content-Type"] = "application/octet-stream" unless names.include?("content-type")
+      headers
+    end
+  end
+end

data/lib/intosql/errors.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module IntoSQL
+  # Everything the gem raises on purpose inherits from this class.
+  class Error < StandardError; end
+
+  # An answer from the IntoSQL API that wasn't a success. `code` doesn't change between versions.
+  class APIError < Error
+    attr_reader :status, :code, :fields, :request_id
+
+    def initialize(status, code, message, fields = {}, request_id = nil)
+      super(message)
+      @status = status
+      @code = code
+      @fields = fields
+      @request_id = request_id
+    end
+  end
+
+  # A conversion that ended as `failed`, with the stable code and the engine's problems.
+  class ConversionFailedError < Error
+    attr_reader :id, :code, :problems
+
+    def initialize(id, failure)
+      super(failure&.message || "Conversion #{id} failed.")
+      @id = id
+      @code = failure&.code || "internal_error"
+      @problems = failure&.problems || []
+    end
+  end
+
+  # A conversion that was canceled while it was awaited.
+  class ConversionCanceledError < Error
+    attr_reader :id
+
+    def initialize(id)
+      super("Conversion #{id} was canceled.")
+      @id = id
+    end
+  end
+
+  # Waiting gave up before the conversion ended; it keeps running on IntoSQL's servers.
+  class TimeoutError < Error
+    attr_reader :id, :status
+
+    def initialize(id, status)
+      super("Conversion #{id} is still #{status}.")
+      @id = id
+      @status = status
+    end
+  end
+
+  # The connection failed (after the retries); `cause` is the network error.
+  class ConnectionError < Error; end
+
+  # A webhook call whose IntoSQL-Signature doesn't match its body.
+  class SignatureError < Error; end
+end

data/lib/intosql/models.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module IntoSQL
+  # The statuses a conversion goes through. The API may add new ones; they arrive as plain strings.
+  module ConversionStatus
+    AWAITING_UPLOAD = "awaiting_upload"
+    QUEUED = "queued"
+    RUNNING = "running"
+    DONE = "done"
+    FAILED = "failed"
+    CANCELED = "canceled"
+    ALL = [AWAITING_UPLOAD, QUEUED, RUNNING, DONE, FAILED, CANCELED].freeze
+  end
+
+  # Builds a struct from an API hash, keeping only the keys it knows.
+  module Model
+    def from_h(hash)
+      new(**hash.slice(*members))
+    end
+  end
+
+  # Why a conversion failed. `code` is stable; new codes may be added within v1.
+  ConversionFailure = Struct.new(:code, :message, :problems, keyword_init: true) do
+    extend Model
+  end
+
+  # A finished conversion's result, downloadable for ten minutes.
+  Output = Struct.new(:bytes, :url, keyword_init: true) do
+    extend Model
+  end
+
+  # Where to send the file, right after `create`: `http_method` (`PUT`), `url` and `headers`.
+  UploadTarget = Struct.new(:http_method, :url, :headers, keyword_init: true) do
+    def self.from_h(hash)
+      new(http_method: hash[:method], url: hash[:url], headers: hash[:headers])
+    end
+  end
+
+  # A conversion as the API answers it. `spec` and `report` are hashes with symbol keys.
+  Conversion = Struct.new(
+    :id, :status, :name, :bytes, :spec, :report, :error, :output, :upload,
+    :created_at, :started_at, :finished_at, :expires_at,
+    keyword_init: true
+  ) do
+    def self.from_h(hash)
+      fields = hash.slice(*members)
+      fields[:error] &&= ConversionFailure.from_h(fields[:error])
+      fields[:output] &&= Output.from_h(fields[:output])
+      fields[:upload] &&= UploadTarget.from_h(fields[:upload])
+      new(**fields)
+    end
+  end
+
+  # A conversion sent to IntoSQL because it didn't come out right.
+  Case = Struct.new(:id, :conversion_id, :share, :status, :created_at, :expires_at, keyword_init: true) do
+    extend Model
+  end
+
+  # Bytes of conversions the plan includes this month, used and left.
+  Usage = Struct.new(:limit, :used, :left, :period_start, keyword_init: true) do
+    extend Model
+  end
+
+  # One page of a list: `data`, `links` (`next`, `prev`) and `meta`.
+  Page = Struct.new(:data, :links, :meta, keyword_init: true) do
+    def self.from_h(hash, &item)
+      new(data: hash.fetch(:data).map(&item), links: hash.fetch(:links), meta: hash[:meta])
+    end
+  end
+
+  # What a webhook call carries. `id` is the same on every retry: handle each event once.
+  # `data` is a Conversion for `conversion.*` events and a hash otherwise (`ping`: `{ sent_at: }`).
+  WebhookEvent = Struct.new(:id, :type, :created_at, :data, keyword_init: true) do
+    def self.from_h(hash)
+      data = hash[:data]
+      data = Conversion.from_h(data) if hash[:type].to_s.start_with?("conversion.") && data.is_a?(Hash)
+      new(**hash.slice(*members), data: data)
+    end
+  end
+end

data/lib/intosql/source.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module IntoSQL
+  # A file to upload: a path (String or Pathname), opened and closed here, or an IO that is
+  # streamed as it is. An IO without `size` (a pipe, a socket) needs `bytes:`.
+  # @api private
+  Source = Struct.new(:io, :bytes, :name, keyword_init: true) do
+    def self.open(file, bytes: nil, name: nil, &)
+      return from_path(file, bytes, name, &) if file.is_a?(String) || file.is_a?(Pathname)
+      return yield from_io(file, bytes, name) if file.respond_to?(:read)
+
+      raise ArgumentError, "Upload a path or an IO, not #{file.class}."
+    end
+
+    def self.from_path(path, bytes, name)
+      File.open(path, "rb") do |io|
+        yield new(io: io, bytes: bytes || io.size, name: name || File.basename(path))
+      end
+    end
+
+    def self.from_io(io, bytes, name)
+      bytes ||= io.size if io.respond_to?(:size)
+      raise ArgumentError, "Pass bytes: with the exact size of this #{io.class}." if bytes.nil?
+
+      path = io.path if io.respond_to?(:path)
+      name ||= File.basename(path) if path
+      new(io: io, bytes: bytes, name: name)
+    end
+  end
+end

data/lib/intosql/spec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Builds conversion specs.
+module IntoSQL
+  # A conversion request with IntoSQL's defaults: types inferred, names in snake_case, batched
+  # inserts. Returns a hash with symbol keys; change it before sending for anything else.
+  def self.spec(dialect:, format: "sql", table: nil, schema: nil, sheet: nil, create_table: true, batch_rows: 500)
+    {
+      version: 1,
+      input: { sheet: sheet, header_row: nil, delimiter: nil, encoding: nil },
+      output: {
+        format: format, dialect: dialect, table: table, schema: schema, create_table: create_table,
+        column_names: "snake_case", style: "inserts", batch_rows: batch_rows
+      },
+      inference: { sample_rows: 10_000, date_order: "auto", keep_leading_zeros: true, locale: nil },
+      columns: []
+    }
+  end
+end

data/lib/intosql/transport.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module IntoSQL
+  # What a transport answers: the status, headers with lowercase names, and the body as a string.
+  Response = Struct.new(:status, :headers, :body, keyword_init: true) do
+    def success?
+      status.between?(200, 299)
+    end
+
+    def header(name)
+      headers[name.downcase]
+    end
+  end
+
+  # The default transport, on `net/http`. A transport is anything with
+  # `call(method:, url:, headers:, body:)` that returns a Response and raises ConnectionError when
+  # the connection fails. `body` is nil, a String, or an IO to stream.
+  class NetHTTPTransport
+    REQUESTS = {
+      "GET" => Net::HTTP::Get,
+      "POST" => Net::HTTP::Post,
+      "PUT" => Net::HTTP::Put,
+      "DELETE" => Net::HTTP::Delete
+    }.freeze
+
+    NETWORK_ERRORS = [
+      IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError, Net::ProtocolError
+    ].freeze
+
+    # `timeout` is in seconds, for connecting, sending and reading each answer.
+    def initialize(timeout: 60)
+      @timeout = timeout
+    end
+
+    def call(method:, url:, headers:, body: nil)
+      uri = URI(url)
+      request = REQUESTS.fetch(method).new(uri, headers)
+      attach(request, body)
+      to_response(connect(uri) { |http| http.request(request) })
+    rescue *NETWORK_ERRORS => e
+      raise ConnectionError, "#{method} #{uri.host} failed: #{e.message}"
+    end
+
+    private
+
+    def to_response(response)
+      Response.new(
+        status: response.code.to_i,
+        headers: response.to_hash.transform_values { |values| values.join(", ") },
+        body: response.body.to_s
+      )
+    end
+
+    def attach(request, body)
+      if body.respond_to?(:read)
+        request.body_stream = body
+      elsif body
+        request.body = body
+      end
+    end
+
+    def connect(uri, &)
+      Net::HTTP.start(
+        uri.host, uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: @timeout, read_timeout: @timeout, write_timeout: @timeout,
+        &
+      )
+    end
+  end
+end

data/lib/intosql/version.rb

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

data/lib/intosql/webhooks.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+# Checks and reads webhook calls.
+module IntoSQL
+  # Whether a webhook call came from IntoSQL: `header` is the `IntoSQL-Signature` header, `body`
+  # the raw request body, `secret` the signing secret from Settings, API keys. `now` (Unix
+  # seconds) fixes the current time in tests.
+  def self.verify_webhook(body, header, secret, tolerance: 300, now: nil)
+    time, signature = Webhook.signature_parts(header)
+    now ||= Time.now.to_i
+
+    return false if time.nil? || signature.nil? || (now - time).abs > tolerance
+
+    expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{time}.".b + body.to_s.b)
+
+    expected.bytesize == signature.bytesize && OpenSSL.fixed_length_secure_compare(expected, signature)
+  end
+
+  # The event of a webhook call, once its signature checks out. Raises SignatureError when it
+  # doesn't, so a forged or replayed call never reaches your code.
+  def self.parse_webhook(body, header, secret, tolerance: 300, now: nil)
+    unless verify_webhook(body, header, secret, tolerance: tolerance, now: now)
+      raise SignatureError, "The IntoSQL-Signature does not match this body."
+    end
+
+    WebhookEvent.from_h(JSON.parse(body, symbolize_names: true))
+  end
+
+  # @api private
+  module Webhook
+    # The timestamp and signature of a `t=TIME,v1=SIGNATURE` header, nil for each one missing.
+    def self.signature_parts(header)
+      parts = header.to_s.split(",").to_h do |part|
+        key, value = part.strip.split("=", -1)
+        [key, value]
+      end
+
+      [Integer(parts["t"].to_s, 10, exception: false), parts["v1"]]
+    end
+  end
+end

data/lib/intosql.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "intosql/version"
+require_relative "intosql/errors"
+require_relative "intosql/models"
+require_relative "intosql/transport"
+require_relative "intosql/source"
+require_relative "intosql/spec"
+require_relative "intosql/webhooks"
+require_relative "intosql/conversions"
+require_relative "intosql/client"
+
+# Convert spreadsheets, CSV and JSON into SQL with the IntoSQL API.
+module IntoSQL
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: intosql
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- IntoSQL
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Upload XLSX, XLS, ODS, CSV or JSON files and get SQL for PostgreSQL,
+  MySQL, MariaDB, SQLite, SQL Server or Oracle back from the IntoSQL API, with webhook
+  verification.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/intosql.rb
+- lib/intosql/client.rb
+- lib/intosql/conversions.rb
+- lib/intosql/errors.rb
+- lib/intosql/models.rb
+- lib/intosql/source.rb
+- lib/intosql/spec.rb
+- lib/intosql/transport.rb
+- lib/intosql/version.rb
+- lib/intosql/webhooks.rb
+homepage: https://intosql.com/docs/sdks/ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://intosql.com/docs/sdks/ruby
+  source_code_uri: https://github.com/alfonsobries/intosql/tree/main/sdks/ruby
+  changelog_uri: https://github.com/alfonsobries/intosql/blob/main/sdks/ruby/CHANGELOG.md
+  documentation_uri: https://intosql.com/docs/sdks/ruby
+  rubygems_mfa_required: 'false'
+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: Convert spreadsheets, CSV and JSON into SQL with the IntoSQL API.
+test_files: []