qube_sync 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b30a43b194aa2be7793bca91ff0af376f35cd0a7a663bcac2cd1297aeddb4cdf
+  data.tar.gz: 6866965f28ddb4a2712b14b37db0230b6d21c5c75885f0bc9910cb5f620ffd4a
+SHA512:
+  metadata.gz: 046c0dd373ee5c9addf3005be16f5279a33f193be25c47d5c45e922d854d7239c10ce12d2529fbc1b60e65fa8ee13d78b4c845450a4273f06fba8960ba406792
+  data.tar.gz: 524e5fb52176085ff61bbd02b79a6765ed53621f6e5b981fb9b26f9c640ff1e4789b7b3ff6511cfaf8fcfd5e6bde6969301ec56fab6bca28c312ba2fa2e04c18

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-01-31
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 qubeintegrations
+
+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,112 @@
+# QUBESync
+
+The QUBESync API is very simple, so this gem is not necessary if you need to use older versions of Ruby or if you prefer to write your own API client. However, if you are using Ruby 2.6 or later and you want to save time, this gem can help you.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add qube_sync
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install qube_sync
+
+## Configuration
+
+You'll need to set two evironment variables in your application to use this gem:
+
+`QUBE_API_KEY` - This is your API key, which you can find in your QUBE Sync application's settings.
+`QUBE_WEBHOOK_SECRET` - This is the secret key used to sign the webhook payloads. You can find this in your QUBE Sync application's settings.
+
+## Usage
+
+```ruby
+require 'qube_sync'
+
+connection_id = QubeSync.create_connection # creates a connection in QUBE on behalf of your user
+#=> "636d4750-0b07-45f6-a030-e3919c5741ff"
+
+# You can also pass a block to create_connection as a success callback
+QubeSync.create_connection do |connection_id|
+  QubeConnection.create!(qube_id: connection_id) # save the connection_id to your database
+end
+
+QubeSync.delete_connection("asdf-qwer-asdf-zxcv") # deletes the connection in QUBE
+#=> true
+
+QubeSync.get_connection(connection_id) # gets the connection in QUBE
+#=> {"id"=>"636d4750-0b07-45f6-a030-e3919c5741ff"}
+
+QubeSync.generate_password(connection_id)
+#=> "password123"
+
+QubeSync.get_qwc(connection_id)
+# "<?xml version=\"1.0\"?>\n<QBWCXML>...</QBWCXML>\n"
+
+
+
+request_xml = <<~XML
+  <?xml version="1.0"?>
+  <?qbxml version="16.0"?>
+  <QBXML>
+    <QBXMLMsgsRq onError="stopOnError">
+      <CustomerQueryRq requestID="1">
+        <MaxReturned>10</MaxReturned>
+      </CustomerQueryRq>
+    </QBXMLMsgsRq>
+  </QBXML>
+XML
+
+QubeSync.queue_request(connection_id, request_xml, webhook_url = "myapp.com/webhook")
+#=> {"id"=>"d401228f-06d4-4981-95d8-bb735c0a2c76",
+#    "state"=>"waiting",
+#    "response_xml"=>nil,
+#    "webhook_url"=>"myapp.com/webhook",
+#    "request_xml"=>
+#     "<?xml version=\"1.0\"?><?qbxml version=\"16.0\"?><QBXML>  ...  </QBXMLMsgsRq></QBXML>"}}
+
+request_id = _.fetch("id")
+
+QubeSync.get_request(request_id)
+#=> {"id"=>"d401228f-06d4-4981-95d8-bb735c0a2c76",
+#    "state"=>"webhook_succeeded",
+#    "response_xml"=>
+#     "<?xml version=\"1.0\" ?> <QBXML> <QBXMLMsgsRs> ... </QBXMLMsgsRs> </QBXML>",
+#    "webhook_url"=>"myapp.com/webhook",
+#    "request_xml"=>
+#     "<?xml version=\"1.0\"?><?qbxml version=\"16.0\"?><QBXML>  ...  </QBXMLMsgsRq></QBXML>"}}
+
+QubeSync.get_requests(connection_id)
+#=> [{"id"=>"d401228f-06d4-4981-95d8-bb735c0a2c76",
+#     "state"=>"webhook_succeeded",
+#     "response_xml"=>
+#      "<?xml version=\"1.0\" ?> <QBXML> <QBXMLMsgsRs> ... </QBXMLMsgsRs> </QBXML>",
+#     "webhook_url"=>"myapp.com/webhook",
+#     "request_xml"=>
+#      "<?xml version=\"1.0\"?><?qbxml version=\"16.0\"?><QBXML>  ...  </QBXMLMsgsRq></QBXML>"}]
+
+QubeSync.delete_request(request_id)
+#=> true
+
+QubeSync.verify_and_build_webhook!(request.body.read, request.headers['X-Qube-Signature'])
+#=> {
+#  "id"=>"dd8db40a-5169-477a-b9d5-f1a6e5cc96f9",
+#  "timestamp"=>1738620998,
+#  "response_xml"=>
+#   "<?xml version=\"1.0\" ?> <QBXML> <QBXMLMsgsRs> ... </QBXMLMsgsRs> </QBXML>" 
+# }
+
+# The default max age for a webhook is 500ms (0.5 seconds). You can change this by passing a max_age option:
+QubeSync.verify_and_build_webhook!(request.body.read, request.headers['X-Qube-Signature'], max_age: 1_000)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/qubeintegrations/qube_sync.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/qube_sync/version.rb

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

data/lib/qube_sync.rb

@@ -0,0 +1,170 @@
+require_relative "qube_sync/version"
+require "faraday"
+
+module QubeSync
+  class Error < StandardError; end
+  class StaleWebhookError < Error; end
+  class InvalidWebhookSignatureError < Error; end
+  class ConfigError < Error; end
+  
+  module_function
+    
+    def base_url
+      ENV.fetch("QUBE_URL", 'https://qubesync.com/api/v1')
+    end
+  
+    def get(url, headers = {})
+      response = connection.get(url) do |request|
+        request.headers = default_headers.merge(headers)
+      end
+  
+      case response.status
+      when 200..299
+        JSON.parse(response.body)
+      else
+        raise Error.new(<<~ERR
+        Unexpected QUBE response: #{response.status}\n#{response.body}
+  
+        Request: #{url}
+        Headers: #{headers}
+        ERR
+        ) 
+      end
+    end
+  
+    def connection
+      Faraday.new(url: base_url) do |conn| 
+        conn.request :authorization, :basic, api_key, ''
+        conn.request :json
+      end
+    end
+  
+    def post(url, body = nil, headers = {})
+      response = connection.post(url) do |request|
+        request.headers = default_headers.merge(headers)
+        request.body = body.to_json if body
+      end
+  
+      case response.status
+      when 200..299
+        JSON.parse(response.body)
+      else
+        raise Error.new <<~ERR
+        Unexpected QUBE response: #{response.status}\n#{response.body}
+        ERR
+      end
+    end
+  
+    def delete(url, headers = {})
+      response = connection.delete(url) do |request|
+        request.headers = default_headers.merge(headers)
+      end
+  
+      case response.status
+      when 200..299
+        true
+      else
+        raise <<~ERR
+        Unexpected QUBE response: #{response.status}\n#{response.body}
+        ERR
+      end
+    end
+  
+    def create_connection
+      response = post("connections")
+      connection_id = response.dig("data", "id") or raise "Connection ID not found: #{response.pretty_inspect}"
+      yield connection_id if block_given?
+      connection_id
+    end
+  
+    def delete_connection(id)
+      delete("connections/#{id}")
+    end
+  
+    def get_connection(connection_id)
+      get("connections/#{connection_id}").fetch("data")
+    end
+  
+    def queue_request(connection_id, request_xml, webhook_url)
+      url = "connections/#{connection_id}/queued_requests"
+  
+      payload = {
+        queued_request: {
+          request_xml: request_xml,
+          webhook_url: webhook_url,
+        }
+      }
+  
+      post(url, payload).fetch("data")
+    end
+
+    def get_request(id)
+      get("queued_requests/#{id}").fetch("data")
+    end
+
+    def get_requests(connection_id)
+      get("connections/#{connection_id}/queued_requests").fetch("data")
+    end
+  
+    def delete_request(id)
+      delete("queued_requests/#{id}")
+    end
+  
+    def get_qwc(connection_id)
+      post("connections/#{connection_id}/qwc")
+        .fetch('qwc')
+    end
+  
+    def generate_password(connection_id)
+      password = SecureRandom.hex(16)
+      response = post("connections/#{connection_id}/password", { password: password })
+      response.dig("data", "password") or raise "Password not found: #{response.pretty_inspect}"
+    end
+  
+  
+    def extract_signature_meta(header)
+      header.split(',') => [ts, *signatures]
+      {
+        timestamp: ts.split("=").last.to_i,
+        signatures: signatures
+      }
+    end
+  
+    def default_headers
+      {
+        'Content-Type' => 'application/json',
+        'Accept' => 'application/json',
+      }
+    end
+  
+    def api_key
+      ENV.fetch('QUBE_API_KEY')
+    rescue KeyError => e
+      raise ConfigError.new("QUBE_API_KEY not set in environment. Your API key can be found/copied from your application page on https://qubesync.com/.")
+    end
+  
+    def api_secret
+      ENV.fetch('QUBE_WEBHOOK_SECRET')
+    rescue KeyError => e
+      raise ConfigError.new("QUBE_WEBHOOK_SECRET not set in environment. Your webhook secret can be found/copied from your application page on https://qubesync.com/.")
+    end
+  
+    def sign_payload(payload)
+      OpenSSL::HMAC.hexdigest('sha256', api_secret, payload)
+    end
+  
+    def verify_and_build_webhook!(body, signature, max_age: 500)
+      extract_signature_meta(signature) => { timestamp:, signatures:}
+  
+      if timestamp < Time.now.to_i - max_age
+        raise StaleWebhookError.new('Timestamp more than #{max_age}ms old. To increase this, pass a different value for max_age.')
+      end
+      
+      if signatures.detect { |sig| sign_payload(body) == sig }
+        JSON.parse(body)
+      else
+        raise InvalidWebhookSignatureError.new("Webhook signature mismatch")
+      end
+  
+    end
+end

data/qube_sync.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "lib/qube_sync/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "qube_sync"
+  spec.version = QubeSync::VERSION
+  spec.authors = ["Garrett Lancaster"]
+  spec.email = ["support@qubesync.com"]
+
+  spec.summary = "Ruby library for the QUBE Sync API"
+  spec.description = """
+  Easily create and manage QUBE Sync API resources in Ruby.
+
+  Manage connections, queued requests, and more with the QUBE Sync API.
+  """
+  spec.homepage = "https://github.com/qubeintegrations/qube_sync_rb"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/qubeintegrations/qube_sync_rb"
+  spec.metadata["changelog_uri"] = "https://github.com/qubeintegrations/qube_sync_rb/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency "faraday"
+
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/sig/qube_sync.rbs

@@ -0,0 +1,4 @@
+module QubeSync
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: qube_sync
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Garrett Lancaster
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-02-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "\n  Easily create and manage QUBE Sync API resources in Ruby.\n\n  Manage
+  connections, queued requests, and more with the QUBE Sync API.\n  "
+email:
+- support@qubesync.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/qube_sync.rb
+- lib/qube_sync/version.rb
+- qube_sync.gemspec
+- sig/qube_sync.rbs
+homepage: https://github.com/qubeintegrations/qube_sync_rb
+licenses: []
+metadata:
+  homepage_uri: https://github.com/qubeintegrations/qube_sync_rb
+  source_code_uri: https://github.com/qubeintegrations/qube_sync_rb
+  changelog_uri: https://github.com/qubeintegrations/qube_sync_rb/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Ruby library for the QUBE Sync API
+test_files: []