v1.0.0

Migration guide

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

The new SDK has a smaller bundle size, 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 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.devices.get(device_id)
+ seam.devices.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 })

The waitForCompletion option was removed, watch for relevant access_code.* events or poll the resource as needed:

- seam.accessCodes.update({ access_code_id }, { waitForCompletion:  true })
+ seam.accessCodes.update({ access_code_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: Instead, you should wait for the access_code.deleted event.
• seam.noiseSensors.noiseThresholds.delete: Instead, you should wait for the noise_threshold.deleted event.
• seam.accessCodes.unmanaged.convertToManaged: Instead, you should wait for the access_code.unmanaged.converted_to_managed and access_code.unmanaged.failed_to_convert_to_managed events.
• seam.accessCodes.update: Instead, you should watch for relevant access_code.* events or poll the resource as needed.
• seam.noiseSensors.noiseThresholds.update: Instead, you should watch for relevant noise_threshold.* events or poll the resource as needed.
• seam.thermostats.climateSettingSchedules.update: Instead, you should watch for relevant climate_setting_schedule.* events or poll the resource as needed.

The following methods now return a NoiseThreshold:

• seam.noiseSensors.noiseThresholds.create: Instead, you should use the newly-created resource ID to poll or watch for events.

Action attempt resolution

Methods that return action attempts still 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.

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.
await seam.locks.unlockDoor(
  { device_id },
  {
    waitForActionAttempt: true,
  },
)

// Wait up to 10 seconds for the action attempt to be ready, checking every 2 seconds.
await seam.locks.unlockDoor(
  { device_id },
  {
    waitForActionAttempt: {
      pollingInterval: 2_000,
      timeout: 10_000,
    },
  },
)

Set default behavior

const seam = new Seam({
  waitForActionAttempt: true,
})

await seam.locks.unlockDoor({ device_id })

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)

Replaced SeamMalformedInputError

Removed SeamMalformedInputError. Instead, use SeamHttpInvalidInputError and the getValidationErrorMessages method.

- if (error instanceof SeamMalformedInputError) {
+ if (error instanceof SeamHttpInvalidInputError) {
-  const messages = error.validationErrors["code"]?._errors ?? []
+  const messages = error.getValidationErrorMessages('code')
}

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.

Using Personal Access Tokens without a Workspace ID

Use SeamMultiWorkspace to call the subset of Seam API endpoints that allow authentication with a personal access token without a workspace ID.

- const seam = new Seam({ personalAccessToken: 'your-personal-access-token' })
- const workspace = seam.workspaces.create({ company_name: 'Example Inc.' })
+ const seamMultiWorkspace = new SeamMultiWorkspace({ personalAccessToken: 'your-personal-access-token' })
+ const workspace = seamMultiWorkspace.workspaces.create({ company_name: 'Example Inc.' })

Unimplemented functionality

• Removed the legacy cli from this package. Instead, use https://github.com/seamapi/seam-cli or the online Seam CLI. We plan to include the Seam CLI in a future version of the seam package.