Migration guide from seamapi package

[razor-x]

This issue will track breaking changes, dropped features, or unimplemented features from the current seamapi package. This issue will be used to generate release notes and a migration guide.

Breaking Changes

• The package name is now seam: npm i seam.
• Dropped official support for Node v16.
• The default export is removed.
  • Change import Seam from 'seamapi' to import { Seam } from 'seam'.
• Axios client updated to version 1.
• The "simple types" like Device, ConnectedAccount, etc., have beed removed.
  • These types were outdated and inaccurate.
  • Improved versions will be included again in a future
  • Once re-implemented, they will be defined and exported from https://github.com/seamapi/types/tree/main/src/lib/seam/connect.
  • Until they are reintroduced, users may create equivalent alias via the response types, e.g.,

    import type { DevicesGetResponse } from '@seamapi/http/connect'
    type Device = DevicesGetResponse['device']

• Methods that return action attempts no longer wait for the action attempt to resolve by default.
  • This functionally is now configurable via waitForActionAttempt.
• API method signatures have changed to no longer accept a plain string, pass an object instead.
  • Before: seam.locks.list(connected_account_id) After: seam.locks.list({ connected_account_id })
  • Before: seam.locks.get(device_id) After: seam.locks.get({ device_id })
  • Before: seam.locks.lockDoor(device_id) After: seam.locks.lockDoor({ device_id })
  • Before: seam.locks.unlockDoor(device_id) After: seam.locks.unlockDoor({ device_id })
  • Before: seam.connectWebviews.get(connect_webview_id) After: seam.connectWebviews.get({ connect_webview_id })
  • Before: seam.actionAttempts.get(action_attempt_id) After: seam.actionAttempts.get({ action_attempt_id })
• Ignore the SEAM_WORKSPACE_ID environment variable.
• Do not allow anything expect a Seam API key in the SEAM_API_KEY environment variable.
• Deprecate the SEAM_API_URL environment variable: use SEAM_ENDPOINT instead.
• Removed seam.makeRequest: use the Axios instance on seam.client directly for this advanced use case.
• Seam.getClientSessionToken removed: use Seam.fromPublishableKey instead.
• Errors no longer implement toString() for "pretty output" in development. This seemed non-standard. (Looking for feedback on this one or alternatives.)
• Some methods that used to return action attempts no longer return action attempts. Here are the new return types:

  seam.accessCodes.delete: void
  seam.accessCodes.unmanaged.void: void
  seam.access_codes.update: void
  seam.noise_sensors.noise_thresholds.create: NoiseThreshold
  seam.noise_sensors.noise_thresholds.delete: void
  seam.noise_sensors.noise_thresholds.update: void
  seam.thermostats.climate_setting_schedules.update: void
  

Unimplemented

• Validation errors do not contain the validation error details on the error object.
• CLI removed: use https://github.com/seamapi/seam-cli. This new CLI be included in a later version of seam.

[DebbieAtSeam]

Migration guide

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

New npm package name

Changed the package name from seamapi to seam.

- npm i seamapi
+ npm i seam

Removed default export

Removed the default export. Instead, this package uses named exports.

- import Seam from 'seamapi'
+ import { Seam } from 'seam'

Updated API method signatures

API method signatures no longer accept a plain string. Instead, pass an object, as follows:

- seam.locks.list(connected_account_id)
+ seam.locks.list({ connected_account_id })

- seam.locks.get(device_id)
+ seam.locks.get({ device_id })

- seam.locks.lockDoor(device_id)
+ seam.locks.lockDoor({ device_id })

- seam.locks.unlockDoor(device_id)
+ seam.locks.unlockDoor({ device_id })

- seam.connectWebviews.get(connect_webview_id)
+ seam.connectWebviews.get({ connect_webview_id })

- seam.actionAttempts.get(action_attempt_id)
+ seam.actionAttempts.get({ action_attempt_id })

Return value changes

Changed the return types for some methods that previously returned action attempts.

The following methods now return void:

• seam.accessCodes.delete: Wait for the access_code.deleted event.
• seam.noiseSensors.noiseThresholds.delete: Wait for the noise_threshold.deleted event.
• seam.accessCodes.unmanaged.convertToManaged: Wait for the access_code.unmanaged.converted_to_managed and access_code.unmanaged.failed_to_convert_to_managed events.
• seam.accessCodes.update: Watch for relevant access_code.* events or poll the resource as needed.
• seam.noiseSensors.noiseThresholds.update: Watch for relevant noise_threshold.* events or poll the resource as needed.
• seam.thermostats.climateSettingSchedules.update: Watch for relevant climate_setting_schedule.* events or poll the resource as needed.

The following methods now return a NoiseThreshold:

• seam.noiseSensors.noiseThresholds.create: Use the newly-created resource ID to poll or watch for events.

Action attempt resolution

Methods that return action attempts no longer wait for the action attempt to resolve by default. Further, you can now configure this behavior using the waitForActionAttempt option on a per-request basis. You can also set the default behavior for the client.

Replaced Seam.getClientSessionToken

Removed Seam.getClientSessionToken. Instead, use Seam.fromPublishableKey.

- const { client_session } = await Seam.getClientSessionToken({ publishableKey, userIdentifierKey })
- const seam = new Seam({ clientSessionToken: client_session?.token })
+ const seam = await SeamHttp.fromPublishableKey(publishableKey, userIdentifierKey)

Environment variables

• Ignore the SEAM_WORKSPACE_ID environment variable.
• Do not allow anything except a Seam API key in the SEAM_API_KEY environment variable.
• Deprecated the SEAM_API_URL environment variable. Instead, use SEAM_ENDPOINT.

See the guide on Authentication Methods for where to specify these values.

Error formatting

Errors no longer implement toString() for "pretty output" in development. This change corrects non-standard behavior. We welcome your feedback and suggestions for error formatting.

Third-party component support and version changes

• Dropped official support for Node v16.
• Updated the Axios client to version 1.

Replaced seam.makeRequest

Removed seam.makeRequest. Instead, use the Axios instance on seam.client directly for this advanced use case.

Unimplemented functionality

• Validation errors do not contain the validation error details on the error object.
• Removed the Seam CLI from this package. Instead, use https://github.com/seamapi/seam-cli. We plan to include the Seam CLI in a future version of the seam package.

[razor-x]

Coming up and will be added as a note in the migration guide: The types have been completely replaced and are now always consistent with the method return types. The previous types were inconsistent, both in name, properties, and definitions. The new types are 🔥