Migration guide from seamapi Ruby gem

[razor-x]

See for reference seamapi/javascript#1 or seamapi/python#7

[andrii-balitskyi]

Migration guide from seamapi to seam

Learn how to migrate from the seamapi package to the seam package. This guide includes descriptions of all breaking changes.

The new SDK has fewer dependencies and is generated daily to ensure methods and types are always up-to-date with the latest API changes. It is mostly a drop-in replacement, however some method signatures and options have changed to improve overall consistency with the Seam API.

This guide includes descriptions of all breaking changes. Please refer to the README for updated usage instructions and a complete list of new features.

New Ruby gem name

Changed the gem name from seamapi to seam.

- bundle add seamapi
+ bundle add seam

Simplified main class initialization

The main class has been renamed from Seam::Client to Seam. You can now initialize it directly:

seam = Seam.new(api_key: "my-api-key")

Updated API method signatures

Keyword arguments

API method signatures now only accept keyword arguments.

- seam.access_codes.get("my_access_code_id")
+ seam.access_codes.get(access_code_id: "my_access_code_id")

- seam.locks.get("my_lock_device_id")
+ seam.locks.get(device_id: "my_lock_device_id")

Standardized resource ID arguments

Changed from accepting both resource objects and resource ID strings to accepting only resource ID strings. Includes a renaming scheme for clarity.

- def unlock_door(device_or_id)
+ def unlock_door(device_id:)

Usage

- seam.locks.get(device: my_device)
+ seam.locks.get(device_id: my_device.device_id)

Removed methods

Removed wait_until_finished from ActionAttempt resource. To resolve an action attempt returned by the method, use the wait_for_action_attempt method argument instead.

- seam.locks.unlock_door(device_id: "my_device_id").wait_until_finished
+ seam.locks.unlock_door(device_id: "my_device_id", wait_for_action_attempt: true)

Removed constructor argument

Removed the debug argument from the Seam class constructor.

Renamed constructor argument

Renamed the base_uri argument to endpoint for overriding the default API endpoint.

Deprecated methods

seam.unmanaged_access_codes

seam.unmanaged_access_codes is now deprecated, use seam.access_codes.unmanaged instead.

- seam.unmanaged_access_codes.get(access_code_id: "my_access_code_id")
+ seam.access_codes.unmanaged.get(access_code_id: "my_access_code_id")

seam.unmanaged_devices

seam.unmanaged_devices is now deprecated, use seam.devices.unmanaged instead.

- seam.unmanaged_devices.get(device_id: "my_device_id")
+ seam.devices.unmanaged.get(device_id: "my_device_id")

Return value changes

Changed the return values for some methods to enhance API consistency and reliability.

The following methods now return nil:

• access_codes.delete: Instead, you should wait for the access_code.deleted event.
• access_codes.update: Instead, you should watch for relevant access_code.* events or poll the resource as needed.
• access_codes.unmanaged.delete
• access_codes.unmanaged.convert_to_managed: Instead, you should wait for the access_code.unmanaged.converted_to_managed and access_code.unmanaged.failed_to_convert_to_managed events.

The following methods now return an ActionAttempt:

• workspaces.reset_sandbox: Instead, you should use the newly-created action_attempt_id to poll the status of the action attempt via the /action_attempt/get endpoint.

Action attempt resolution

Now all methods returning action attempts wait for the action attempt to resolve by default. Furether, you can configure this behavior using the wait_for_action_attempt option on a per-request basis. You can also set the default behavior for the client.

Set per request

# Wait for the action attempt to be ready with a default timeout of 5.0 seconds and a default polling interval of 0.5 seconds.
seam.locks.lock_door(
  device_id: "my_device_id",
  wait_for_action_attempt: false
)

# Wait up to 10 seconds for the action attempt to be ready, checking every 2 seconds.
seam.locks.lock_door(
  device_id: "my_device_id",
  wait_for_action_attempt: {
    timeout: 10.0,  # Up to 10 seconds
    polling_interval: 2.0  # Every 2 seconds
  }
)

Set default behavior

seam = Seam.new(wait_for_action_attempt: false)

Environment variables

The SEAM_API_URL environment variable is now deprecated. Please use SEAM_ENDPOINT instead.

Version changes

• Updated the minimum supported Ruby version to 3.1.0.

Highlighted new features

API key authentication with from_api_key factory method

Added a new from_api_key factory method for API key authentication of the Seam client.

seam = Seam.from_api_key("your-api-key")

PAT authentication scoped to a single workspace

Added support for workspace personal access token (PAT) authentication.

# 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",
)

PAT authentication not bound to a specific workspace

For authentication with a personal access token not bound to a specific workspace, use Seam::Http::SeamMultiWorkspace.

# Pass as an option to the constructor
seam_multi_workspace = Seam::Http::SeamMultiWorkspace.new(personal_access_token: "your-personal-access-token")

# Use the factory method
seam_multi_workspace = Seam::Http::SeamMultiWorkspace.from_personal_access_token(
  "your-personal-access-token"
)

workspace = seam_multi_workspace.workspaces.create(company_name: "Example Inc.")

Webhook handler

SDK exports a thin wrapper Seam::Webhook around the svix package. Use it to parse and validate Seam webhook events.

New configurable Faraday HTTP client with retry options

The Ruby SDK now uses the Faraday HTTP client under the hood, which can be configured using faraday_options and faraday_retry_options.

seam = Seam.new(
  api_key: "your-api-key",
  faraday_options: {
    headers: {
      "Custom-Header": "Custom-Value"
    }
  },
  faraday_retry_options: {
    max: 3,
    backoff_factor: 2
  }
)

The Faraday client is also exposed via the seam.client property and can be used or configured directly:

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"]

[andrii-balitskyi]

@razor-x here's the first version of migration guide. Some things are still not implemented, like:

• allow using Seam.new and not Seam::Client.new
• rename ClientMultiWorkspace to SeamMultiWorkspace Seam::Http::MultiWorkspace and expose it from the SDK to be used as Seam::Http::MultiWorkspace.new without the Seam namespace
• add SeamWebhook Seam::Webhook
• document SDK usage in README.md for the links inside the guide to work correctly

[razor-x]

@andrii-balitskyi We don't need to add more top level name, we can keep Seam::Webhook and Seam::Http::MultiWorkspace (this last one is a more advanced use case anyway). Refer back to this issue for the target structure we worked on #115

[andrii-balitskyi]

@razor-x Yes, that's how we implemented it. The comment you're referring to is outdated (from August 7th, we didn't agree on the new structure at the time). I've updated it to avoid confusion.

[DebbieAtSeam]

Migration guide

Learn how to migrate from the seamapi package to the seam package.

The new SDK has fewer dependencies and is generated daily to ensure methods and types are always up-to-date with the latest API changes. It is mostly a drop-in replacement, however some method signatures and options have changed to improve overall consistency with the Seam API.

This guide includes descriptions of all breaking changes. Please refer to the README for updated usage instructions and a complete list of new features.

New Ruby gem name

Changed the gem name from seamapi to seam.

- bundle add seamapi
+ bundle add seam

Simplified main class initialization

The main class has been renamed from Seam::Client to Seam. You can now initialize it directly.

seam = Seam.new(api_key: "your-api-key")

Specify your-api-key during initialization, or Seam automatically uses your exported SEAM_API_KEY.

Updated API method signatures

Keyword arguments

API method signatures now only accept keyword arguments.

- seam.access_codes.get("your-access-code-id")
+ seam.access_codes.get(access_code_id: "your-access-code-id")

- seam.devices.get("your-device-id")
+ seam.devices.get(device_id: "your-device-id")

Standardized resource ID arguments

Changed from accepting both resource objects and resource ID strings to accepting only resource ID strings. Includes a renaming scheme for clarity.

- def unlock_door(device_or_id)
+ def unlock_door(device_id:)

Usage

- seam.devices.get(device: your_device)
+ seam.devices.get(device_id: your_device.device_id)

Removed methods

Removed wait_until_finished from ActionAttempt resource. To resolve an action attempt returned by the method, use the wait_for_action_attempt method argument instead.

- seam.locks.unlock_door(device_id: "your-device-id").wait_until_finished
+ seam.locks.unlock_door(device_id: "your-device-id", wait_for_action_attempt: true)

Removed constructor argument

Removed the debug argument from the Seam class constructor.

Renamed constructor argument

Renamed the base_uri argument to endpoint for overriding the default API endpoint.

Deprecated methods

seam.unmanaged_access_codes

seam.unmanaged_access_codes is now deprecated. Use seam.access_codes.unmanaged instead.

- seam.unmanaged_access_codes.get(access_code_id: "your-access-code-id")
+ seam.access_codes.unmanaged.get(access_code_id: "your-access-code-id")

seam.unmanaged_devices

seam.unmanaged_devices is now deprecated. Use seam.devices.unmanaged instead.

- seam.unmanaged_devices.get(device_id: "your-device-id")
+ seam.devices.unmanaged.get(device_id: "your-device-id")

Return value changes

Changed the return values for some methods to enhance API consistency and reliability.

The following methods now return nil:

• access_codes.delete: Instead, you should wait for the access_code.deleted event.
• access_codes.update: Instead, you should watch for relevant access_code.* events or poll the resource as needed.
• access_codes.unmanaged.delete
• access_codes.unmanaged.convert_to_managed: Instead, you should wait for the access_code.unmanaged.converted_to_managed and access_code.unmanaged.failed_to_convert_to_managed events.

The following methods now return an ActionAttempt:

• workspaces.reset_sandbox: Instead, you should use the newly-created action_attempt_id to poll the status of the action attempt using seam.action_attempts.get.

Action attempt resolution

Now, all methods returning action attempts wait for the action attempt to resolve by default. Further, you can configure this behavior using the wait_for_action_attempt option on a per-request basis. You can also set the default behavior for the client.

Set per request

# Wait for the action attempt to be ready with a default timeout of 5.0 seconds and a default polling interval of 0.5 seconds.
seam.locks.lock_door(
  device_id: "your-device-id",
  wait_for_action_attempt: false
)

# Wait up to 10 seconds for the action attempt to be ready, checking every 2 seconds.
seam.locks.lock_door(
  device_id: "your-device-id",
  wait_for_action_attempt: {
    timeout: 10.0,  # Up to 10 seconds
    polling_interval: 2.0  # Every 2 seconds
  }
)

Set default behavior

seam = Seam.new(wait_for_action_attempt: false)

Environment variables

The SEAM_API_URL environment variable is now deprecated. Use SEAM_ENDPOINT instead.

Version changes

Updated the minimum supported Ruby version to 3.1.0.

Highlighted new features

API key authentication with from_api_key factory method

Added a new from_api_key factory method for API key authentication of the Seam client.

seam = Seam.from_api_key("your-api-key")

PAT authentication scoped to a single workspace

Added support for workspace personal access token (PAT) authentication.

# 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",
)

PAT authentication not bound to a specific workspace

For authentication with a personal access token not bound to a specific workspace, use Seam::Http::SeamMultiWorkspace.

# Pass as an option to the constructor.
seam_multi_workspace = Seam::Http::SeamMultiWorkspace.new(personal_access_token: "your-personal-access-token")

# Use the factory method.
seam_multi_workspace = Seam::Http::SeamMultiWorkspace.from_personal_access_token(
  "your-personal-access-token"
)

workspace = seam_multi_workspace.workspaces.create(company_name: "Example Inc.")

Webhook handler

The Ruby SDK exports a thin wrapper Seam::Webhook around the svix package. Use it to parse and validate Seam webhook events.

New configurable Faraday HTTP client with retry options

The Ruby SDK now uses the Faraday HTTP client under the hood, which you can configure using faraday_options and faraday_retry_options.

seam = Seam.new(
  api_key: "your-api-key",
  faraday_options: {
    headers: {
      "Custom-Header": "Custom-Value"
    }
  },
  faraday_retry_options: {
    max: 3,
    backoff_factor: 2
  }
)

The Faraday client is also exposed through the seam.client property and can be used or configured directly.

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"]