seam 2.0.0a2 → 2.0.0b0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bb7a5a7828d18d2b54017d76ed325d0e7e25c482de942eca0330da40f7e1105
-  data.tar.gz: 8a86ca467008bb6f8d2b76394f9f773a938f072a384a29dc78dc16e430917bb3
+  metadata.gz: f62e294d25f9d5ed9508e9b5d240197d5a92809dbbbb31719722fb6075fecf85
+  data.tar.gz: 51621ca4919764d502838e432d7722949ef504e1629bdb224a103d432cfc94ab
 SHA512:
-  metadata.gz: 138e121c4bc2482ca27d3a74df486effb52d749de8e1af57fa95ec20600c109e7b2779794e2724fbe8436192ce3a40481e693857ca19b99a320ca96fe4623fe6
-  data.tar.gz: 4ae84ca5a842777f890f5df0cbff9252fa22d9658f7d03422abcb992a1412e1a272a538019c0f436290bb0064dea0344292690a919a4aa305ec7b3d84e96a30b
+  metadata.gz: dc17fcb3c4583ccedf6aed31be275ca76ad721ed2364ac3820580ecd5954f4bb778a85e66eb26a804cc20ede4dd2aad8db1a7206ad5d829f3bfd40de6187e520
+  data.tar.gz: 15de1ddba2b3b0d727aca93235634fa2fb60aece82a6238f06474c8795af1f7f8cd3b4f240d1facfe9d6ee0bc665bc91cae4af9ed8903a14da1b81f58c4190c2

data/Gemfile.lock

@@ -1,117 +1,120 @@
 PATH
   remote: .
   specs:
-    seam (2.0.0a2)
-      http (~> 5.2)
+    seam (2.0.0b0)
+      faraday (~> 2.7)
+      faraday-retry (~> 2.2)
+      svix (~> 1.30)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.6)
-      public_suffix (>= 2.0.2, < 6.0)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
     ansi (1.5.0)
     ast (2.4.2)
-    base64 (0.2.0)
-    bigdecimal (3.1.7)
+    bigdecimal (3.1.8)
     crack (1.0.0)
       bigdecimal
       rexml
     diff-lcs (1.5.1)
-    docile (1.4.0)
-    domain_name (0.6.20240107)
-    ffi (1.16.3)
-    ffi-compiler (1.3.2)
-      ffi (>= 1.15.5)
-      rake
+    docile (1.4.1)
+    ethon (0.16.0)
+      ffi (>= 1.15.0)
+    faraday (2.12.0)
+      faraday-net_http (>= 2.0, < 3.4)
+      json
+      logger
+    faraday-net_http (3.3.0)
+      net-http
+    faraday-retry (2.2.1)
+      faraday (~> 2.0)
+    ffi (1.17.0)
+    ffi (1.17.0-x86_64-linux-gnu)
     gem-release (2.2.2)
-    hashdiff (1.1.0)
-    http (5.2.0)
-      addressable (~> 2.8)
-      base64 (~> 0.1)
-      http-cookie (~> 1.0)
-      http-form_data (~> 2.2)
-      llhttp-ffi (~> 0.5.0)
-    http-cookie (1.0.5)
-      domain_name (~> 0.5)
-    http-form_data (2.3.0)
+    hashdiff (1.1.1)
     json (2.7.2)
     language_server-protocol (3.17.0.3)
     lint_roller (1.1.0)
-    llhttp-ffi (0.5.0)
-      ffi-compiler (~> 1.0)
-      rake (~> 13.0)
+    logger (1.6.1)
     multi_json (1.15.0)
-    parallel (1.24.0)
+    net-http (0.4.1)
+      uri
+    parallel (1.26.3)
     parse_gemspec (1.0.0)
     parse_gemspec-cli (1.0.0)
       multi_json
       parse_gemspec
       thor
-    parser (3.3.0.5)
+    parser (3.3.5.0)
       ast (~> 2.4.1)
       racc
-    public_suffix (5.0.5)
-    racc (1.7.3)
+    public_suffix (6.0.1)
+    racc (1.8.1)
     rainbow (3.1.1)
     rake (13.2.1)
-    regexp_parser (2.9.0)
-    rexml (3.2.6)
+    regexp_parser (2.9.2)
+    rexml (3.3.8)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.0)
+    rspec-core (3.13.2)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.0)
+    rspec-expectations (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.0)
+    rspec-mocks (3.13.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
-    rubocop (1.62.1)
+    rubocop (1.66.1)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+      regexp_parser (>= 2.4, < 3.0)
+      rubocop-ast (>= 1.32.2, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.2)
-      parser (>= 3.3.0.4)
-    rubocop-performance (1.20.2)
+    rubocop-ast (1.32.3)
+      parser (>= 3.3.1.0)
+    rubocop-performance (1.22.1)
       rubocop (>= 1.48.1, < 2.0)
-      rubocop-ast (>= 1.30.0, < 2.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
     ruby-progressbar (1.13.0)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-console (0.9.1)
+    simplecov-console (0.9.2)
       ansi
       simplecov
       terminal-table
-    simplecov-html (0.12.3)
+    simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
-    standard (1.35.1)
+    standard (1.41.1)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.62.0)
+      rubocop (~> 1.66.0)
       standard-custom (~> 1.0.0)
-      standard-performance (~> 1.3)
+      standard-performance (~> 1.5)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.3.1)
+    standard-performance (1.5.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.20.2)
+      rubocop-performance (~> 1.22.0)
+    svix (1.38.0)
+      typhoeus (~> 1.0, >= 1.0.1)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
-    thor (1.3.1)
-    unicode-display_width (2.5.0)
+    thor (1.3.2)
+    typhoeus (1.4.1)
+      ethon (>= 0.9.0)
+    unicode-display_width (2.6.0)
+    uri (0.13.1)
     webmock (3.0.1)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)

data/README.md

@@ -7,17 +7,337 @@ SDK for the Seam API written in Ruby.
 
 ## Description
 
-TODO
+[Seam](https://seam.co) makes it easy to integrate IoT devices with your applications.
+This is an official SDK for the Seam API.
+Please refer to the official [Seam Docs](https://docs.seam.co/latest/) to get started.
+
+Parts of this SDK are generated from always up-to-date type information
+provided by [@seamapi/types](https://github.com/seamapi/types/).
+This ensures all API methods, request shapes, and response shapes are
+accurate and fully typed.
+
+<!-- toc -->
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Examples](#examples)
+    - [List devices](#list-devices)
+    - [Unlock a door](#unlock-a-door)
+  - [Authentication Method](#authentication-method)
+    - [API Key](#api-key)
+    - [Personal Access Token](#personal-access-token)
+  - [Action Attempts](#action-attempts)
+  - [Interacting with Multiple Workspaces](#interacting-with-multiple-workspaces)
+  - [Webhooks](#webhooks)
+  - [Advanced Usage](#advanced-usage)
+    - [Additional Options](#additional-options)
+    - [Setting the endpoint](#setting-the-endpoint)
+    - [Configuring the Faraday Client](#configuring-the-faraday-client)
+    - [Using the Faraday Client](#using-the-faraday-client)
+    - [Overriding the Client](#overriding-the-client)
+- [Development and Testing](#development-and-testing)
+  - [Quickstart](#quickstart)
+  - [Source code](#source-code)
+  - [Requirements](#requirements)
+  - [Publishing](#publishing)
+    - [Automatic](#automatic)
+    - [Manual](#manual)
+- [GitHub Actions](#github-actions)
+  - [Secrets for Optional GitHub Actions](#secrets-for-optional-github-actions)
+- [Contributing](#contributing)
+- [License](#license)
+- [Warranty](#warranty)
+
+<!-- tocstop -->
 
 ## Installation
 
-Add this as a dependency to your project using [Bundler] with
+Add this as a dependency to your project using [Bundler] with:
 
 ```
 $ bundle add seam
 ```
 
-[bundler]: https://bundler.io/
+[Bundler]: https://bundler.io/
+
+## Usage
+
+### Examples
+
+> [!NOTE]
+> These examples assume `SEAM_API_KEY` is set in your environment.
+
+#### List devices
+
+```ruby
+require "seam"
+
+seam = Seam.new
+devices = seam.devices.list
+```
+
+#### Unlock a door
+
+```ruby
+require "seam"
+
+seam = Seam.new
+lock = seam.locks.get(name: "Front Door")
+seam.locks.unlock_door(device_id: lock.device_id)
+```
+
+### Authentication Method
+
+The SDK supports API key and personal access token authentication mechanisms.
+Authentication may be configured by passing the corresponding options directly to the `Seam` constructor, or with the more ergonomic static factory methods.
+
+#### API Key
+
+An API key is scoped to a single workspace and should only be used on the server.
+Obtain one from the Seam Console.
+
+```ruby
+# Set the `SEAM_API_KEY` environment variable
+seam = Seam.new
+
+# Pass as a keyword argument to the constructor
+seam = Seam.new(api_key: "your-api-key")
+
+# Use the factory method
+seam = Seam.from_api_key("your-api-key")
+```
+
+#### Personal Access Token
+
+A Personal Access Token is scoped to a Seam Console user.
+Obtain one from the Seam Console.
+A workspace ID must be provided when using this method and all requests will be scoped to that workspace.
+
+```ruby
+# Pass as an option to the constructor
+seam = Seam.new(
+  personal_access_token: "your-personal-access-token",
+  workspace_id: "your-workspace-id"
+)
+
+# Use the factory method
+seam = Seam.from_personal_access_token(
+  "your-personal-access-token",
+  "your-workspace-id"
+)
+```
+
+### Action Attempts
+
+Some asynchronous operations, e.g., unlocking a door, return an
+[action attempt](https://docs.seam.co/latest/core-concepts/action-attempts).
+Seam tracks the progress of the requested operation and updates the action attempt
+when it succeeds or fails.
+
+To make working with action attempts more convenient for applications,
+this library provides the `wait_for_action_attempt` option and enables it by default.
+
+When the `wait_for_action_attempt` option is enabled, the SDK:
+
+- Polls the action attempt up to the `timeout`
+  at the `polling_interval` (both in seconds).
+- Resolves with a fresh copy of the successful action attempt.
+- Raises a `Seam::ActionAttemptFailedError` if the action attempt is unsuccessful.
+- Raises a `Seam::ActionAttemptTimeoutError` if the action attempt is still pending when the `timeout` is reached.
+- Both errors expose an `action_attempt` property.
+
+If you already have an action attempt ID
+and want to wait for it to resolve, simply use:
+
+```ruby
+seam.action_attempts.get(action_attempt_id: action_attempt_id)
+```
+
+Or, to get the current state of an action attempt by ID without waiting:
+
+```ruby
+seam.action_attempts.get(
+  action_attempt_id: action_attempt_id,
+  wait_for_action_attempt: false
+)
+```
+
+To disable this behavior, set the default option for the client:
+
+```ruby
+seam = Seam.new(
+  api_key: "your-api-key",
+  wait_for_action_attempt: false
+)
+
+seam.locks.unlock_door(device_id: device_id)
+```
+
+or the behavior may be configured per-request:
+
+```ruby
+seam.locks.unlock_door(
+  device_id: device_id,
+  wait_for_action_attempt: false
+)
+```
+
+The `polling_interval` and `timeout` may be configured for the client or per-request.
+For example:
+
+```ruby
+require "seam"
+
+seam = Seam.new("your-api-key")
+
+locks = seam.locks.list
+
+if locks.empty?
+  raise "No locks in this workspace"
+end
+
+lock = locks.first
+
+begin
+  seam.locks.unlock_door(
+    device_id: lock.device_id,
+    wait_for_action_attempt: {
+      timeout: 5.0,
+      polling_interval: 1.0
+    }
+  )
+
+  puts "Door unlocked"
+rescue Seam::ActionAttemptFailedError
+  puts "Could not unlock the door"
+rescue Seam::ActionAttemptTimeoutError
+  puts "Door took too long to unlock"
+end
+```
+
+### Interacting with Multiple Workspaces
+
+Some Seam API endpoints interact with multiple workspaces. The `Seam::Http::SeamMultiWorkspace` client is not bound to a specific workspace and may use those endpoints with a personal access token authentication method.
+
+A Personal Access Token is scoped to a Seam Console user. Obtain one from the Seam Console.
+
+```ruby
+# Pass as an option to the constructor
+seam = Seam::Http::SeamMultiWorkspace.new(personal_access_token: "your-personal-access-token")
+
+# Use the factory method
+seam = Seam::Http::SeamMultiWorkspace.from_personal_access_token("your-personal-access-token")
+
+# List workspaces authorized for this Personal Access Token
+workspaces = seam.workspaces.list
+```
+
+### Webhooks
+
+The Seam API implements webhooks using [Svix](https://www.svix.com).This SDK exports a thin wrapper `Seam::Webhook` around the svix package.
+Use it to parse and validate Seam webhook events.
+
+> [!TIP]
+> This example is for [Sinatra](https://sinatrarb.com/), see the [Svix docs for more examples in specific frameworks](https://docs.svix.com/receiving/verifying-payloads/how).
+
+```ruby
+require "sinatra"
+require "seam"
+
+webhook = Seam::Webhook.new(ENV["SEAM_WEBHOOK_SECRET"])
+
+post "/webhook" do
+  begin
+    headers = {
+      "svix-id" => request.env["HTTP_SVIX_ID"],
+      "svix-signature" => request.env["HTTP_SVIX_SIGNATURE"],
+      "svix-timestamp" => request.env["HTTP_SVIX_TIMESTAMP"]
+    }
+    data = webhook.verify(request.body.read, headers)
+  rescue Seam::WebhookVerificationError
+    halt 400, "Bad Request"
+  end
+
+  begin
+    store_event(data)
+  rescue
+    halt 500, "Internal Server Error"
+  end
+
+  204
+end
+
+def store_event(data)
+  puts data
+end
+```
+
+### Advanced Usage
+
+#### Additional Options
+
+In addition to the various authentication options,
+the constructor takes some advanced options that affect behavior.
+
+```ruby
+seam = Seam.new(
+  api_key: "your-api-key",
+  endpoint: "https://example.com",
+  faraday_options: {},
+  faraday_retry_options: {}
+)
+```
+
+When using the static factory methods,
+these options may be passed in as keyword arguments.
+
+```ruby
+seam = Seam.from_api_key("some-api-key",
+  endpoint: "https://example.com",
+  faraday_options: {},
+  faraday_retry_options: {})
+```
+
+#### Setting the endpoint
+
+Some contexts may need to override the API endpoint,
+e.g., testing or proxy setups. This option corresponds to the [Faraday](https://lostisland.github.io/faraday/#/) `url` setting.
+
+Either pass the `endpoint` option, or set the `SEAM_ENDPOINT` environment variable.
+
+#### Configuring the Faraday Client
+
+The Faraday client and retry behavior may be configured with custom initiation options
+via [`faraday_option`][faraday_option] and [`faraday_retry_option`][faraday_retry_option].
+
+[faraday_option]: https://lostisland.github.io/faraday/#/customization/connection-options?id=connection-options
+[faraday_retry_option]: https://github.com/lostisland/faraday-retry
+
+#### Using the Faraday Client
+
+The Faraday client is exposed and may be used or configured directly:
+
+```ruby
+require "seam"
+require "faraday"
+
+class MyMiddleware < Faraday::Middleware
+  def on_complete(env)
+    puts env.response.inspect
+  end
+end
+
+seam = Seam.new
+
+seam.client.builder.use MyMiddleware
+
+devices = seam.client.get("/devices/list").body["devices"]
+```
+
+#### Overriding the Client
+
+A Faraday compatible client may be provided to create a `Seam` instance.
+This API is used internally and is not directly supported.
 
 ## Development and Testing
 

data/Rakefile

@@ -5,7 +5,10 @@ require "rspec/core/rake_task"
 require "standard/rake"
 
 RSpec::Core::RakeTask.new(:spec) do |t|
-  t.rspec_opts = "--pattern spec/**/*_spec.rb"
+  t.pattern = [
+    "spec/**/*_spec.rb",
+    "lib/seam/*_spec.rb"
+  ]
 end
 
 task default: %i[lint test]

data/lib/seam/auth.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "options"
+require_relative "token"
+
+module Seam
+  module Http
+    module Auth
+      class SeamInvalidTokenError < StandardError
+        def initialize(message)
+          super("Seam received an invalid token: #{message}")
+        end
+      end
+
+      def self.get_auth_headers(api_key: nil, personal_access_token: nil, workspace_id: nil)
+        if Http::Options.seam_http_options_with_api_key?(api_key: api_key, personal_access_token: personal_access_token)
+          return get_auth_headers_for_api_key(api_key)
+        end
+
+        if Http::Options.seam_http_options_with_personal_access_token?(personal_access_token: personal_access_token, api_key: api_key,
+          workspace_id: workspace_id)
+          return get_auth_headers_for_personal_access_token(personal_access_token, workspace_id)
+        end
+
+        raise Http::Options::SeamInvalidOptionsError.new(
+          "Must specify an api_key or personal_access_token. " \
+          "Attempted reading configuration from the environment, " \
+          "but the environment variable SEAM_API_KEY is not set."
+        )
+      end
+
+      def self.get_auth_headers_for_api_key(api_key)
+        if Auth.client_session_token?(api_key)
+          raise SeamInvalidTokenError.new(
+            "A Client Session Token cannot be used as an api_key"
+          )
+        end
+
+        raise SeamInvalidTokenError.new("A JWT cannot be used as an api_key") if Auth.jwt?(api_key)
+
+        raise SeamInvalidTokenError.new("An Access Token cannot be used as an api_key") if Auth.access_token?(api_key)
+
+        if Auth.publishable_key?(api_key)
+          raise SeamInvalidTokenError.new(
+            "A Publishable Key cannot be used as an api_key"
+          )
+        end
+
+        unless Auth.seam_token?(api_key)
+          raise SeamInvalidTokenError.new(
+            "Unknown or invalid api_key format, expected token to start with #{Auth::TOKEN_PREFIX}"
+          )
+        end
+
+        {"authorization" => "Bearer #{api_key}"}
+      end
+
+      def self.get_auth_headers_for_personal_access_token(personal_access_token, workspace_id)
+        if Auth.jwt?(personal_access_token)
+          raise SeamInvalidTokenError.new(
+            "A JWT cannot be used as a personal_access_token"
+          )
+        end
+
+        if Auth.client_session_token?(personal_access_token)
+          raise SeamInvalidTokenError.new(
+            "A Client Session Token cannot be used as a personal_access_token"
+          )
+        end
+
+        if Auth.publishable_key?(personal_access_token)
+          raise SeamInvalidTokenError.new(
+            "A Publishable Key cannot be used as a personal_access_token"
+          )
+        end
+
+        unless Auth.access_token?(personal_access_token)
+          raise SeamInvalidTokenError.new(
+            "Unknown or invalid personal_access_token format, expected token to start with #{Auth::ACCESS_TOKEN_PREFIX}"
+          )
+        end
+
+        {
+          "authorization" => "Bearer #{personal_access_token}",
+          "seam-workspace" => workspace_id
+        }
+      end
+
+      def self.get_auth_headers_for_multi_workspace_personal_access_token(personal_access_token)
+        if Auth.jwt?(personal_access_token)
+          raise SeamInvalidTokenError.new(
+            "A JWT cannot be used as a personal_access_token"
+          )
+        end
+
+        if Auth.client_session_token?(personal_access_token)
+          raise SeamInvalidTokenError.new(
+            "A Client Session Token cannot be used as a personal_access_token"
+          )
+        end
+
+        if Auth.publishable_key?(personal_access_token)
+          raise SeamInvalidTokenError.new(
+            "A Publishable Key cannot be used as a personal_access_token"
+          )
+        end
+
+        unless Auth.access_token?(personal_access_token)
+          raise SeamInvalidTokenError.new(
+            "Unknown or invalid personal_access_token format, expected token to start with #{Auth::ACCESS_TOKEN_PREFIX}"
+          )
+        end
+
+        {"authorization" => "Bearer #{personal_access_token}"}
+      end
+    end
+  end
+end