@seamapi/http 2.17.0 → 2.19.0

package/src/lib/index.ts

@@ -3,12 +3,15 @@ export * from './error-interceptor.js'
 export * from './openapi.js'
 export * from './options.js'
 export {
+  type FailedActionAttempt,
   isSeamActionAttemptError,
   isSeamActionAttemptFailedError,
   isSeamActionAttemptTimeoutError,
+  type ResolveActionAttemptOptions,
   SeamActionAttemptError,
   SeamActionAttemptFailedError,
   SeamActionAttemptTimeoutError,
+  type SucceededActionAttempt,
 } from './resolve-action-attempt.js'
 export * from './resources/index.js'
 export * from './routes/index.js'

package/src/lib/options.ts

@@ -6,12 +6,19 @@ import {
 
 export type { SeamHttpRequestOptions } from './request-options.js'
 
+/**
+ * Options for creating a SeamHttpWithoutWorkspace client,
+ * which is not scoped to a single workspace.
+ */
 export type SeamHttpWithoutWorkspaceOptions =
   | SeamHttpWithoutWorkspaceOptionsFromEnv
   | SeamHttpWithoutWorkspaceOptionsWithClient
   | SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken
   | SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken
 
+/**
+ * Options for creating a SeamHttp client.
+ */
 export type SeamHttpOptions =
   | SeamHttpOptionsFromEnv
   | SeamHttpOptionsWithClient
@@ -21,28 +28,62 @@ export type SeamHttpOptions =
   | SeamHttpOptionsWithPersonalAccessToken
 
 interface SeamHttpCommonOptions extends ClientOptions, SeamHttpRequestOptions {
+  /**
+   * The Seam API endpoint, e.g., `https://connect.getseam.com`.
+   * Defaults to the SEAM_ENDPOINT or SEAM_API_URL environment variable, if set.
+   */
   endpoint?: string
 }
 
+/**
+ * Options for creating a SeamHttp client with `SeamHttp.fromPublishableKey`.
+ */
 export interface SeamHttpFromPublishableKeyOptions extends SeamHttpCommonOptions {}
 
+/**
+ * Options for creating a SeamHttp client that reads its configuration
+ * from the environment, e.g., the SEAM_API_KEY environment variable.
+ */
 export interface SeamHttpOptionsFromEnv extends SeamHttpCommonOptions {}
 
+/**
+ * Options for creating a SeamHttpWithoutWorkspace client that reads
+ * its configuration from the environment,
+ * e.g., the SEAM_PERSONAL_ACCESS_TOKEN environment variable.
+ */
 export interface SeamHttpWithoutWorkspaceOptionsFromEnv extends SeamHttpCommonOptions {}
 
+/**
+ * Options for creating a SeamHttpWithoutWorkspace client from an existing client.
+ */
 export interface SeamHttpWithoutWorkspaceOptionsWithClient extends SeamHttpCommonOptions {
   client: Client
 }
 
+/**
+ * Returns true if the options include a client.
+ *
+ * @throws {@link SeamHttpInvalidOptionsError} if the client option
+ * is used with any other option.
+ */
 export const isSeamHttpWithoutWorkspaceOptionsWithClient = (
   options: SeamHttpOptions,
 ): options is SeamHttpWithoutWorkspaceOptionsWithClient =>
   isSeamHttpOptionsWithClient(options)
 
+/**
+ * Options for creating a SeamHttp client from an existing client.
+ */
 export interface SeamHttpOptionsWithClient extends SeamHttpRequestOptions {
   client: Client
 }
 
+/**
+ * Returns true if the options include a client.
+ *
+ * @throws {@link SeamHttpInvalidOptionsError} if the client option
+ * is used with any other option.
+ */
 export const isSeamHttpOptionsWithClient = (
   options: SeamHttpOptions,
 ): options is SeamHttpOptionsWithClient => {
@@ -61,10 +102,19 @@ export const isSeamHttpOptionsWithClient = (
   return true
 }
 
+/**
+ * Options for creating a SeamHttp client authenticated with an API key.
+ */
 export interface SeamHttpOptionsWithApiKey extends SeamHttpCommonOptions {
   apiKey: string
 }
 
+/**
+ * Returns true if the options include an apiKey.
+ *
+ * @throws {@link SeamHttpInvalidOptionsError} if the apiKey option
+ * is used with another authentication option.
+ */
 export const isSeamHttpOptionsWithApiKey = (
   options: SeamHttpOptions,
 ): options is SeamHttpOptionsWithApiKey => {
@@ -92,10 +142,19 @@ export const isSeamHttpOptionsWithApiKey = (
   return true
 }
 
+/**
+ * Options for creating a SeamHttp client authenticated with a client session token.
+ */
 export interface SeamHttpOptionsWithClientSessionToken extends SeamHttpCommonOptions {
   clientSessionToken: string
 }
 
+/**
+ * Returns true if the options include a clientSessionToken.
+ *
+ * @throws {@link SeamHttpInvalidOptionsError} if the clientSessionToken option
+ * is used with another authentication option.
+ */
 export const isSeamHttpOptionsWithClientSessionToken = (
   options: SeamHttpOptions,
 ): options is SeamHttpOptionsWithClientSessionToken => {
@@ -123,10 +182,20 @@ export const isSeamHttpOptionsWithClientSessionToken = (
   return true
 }
 
+/**
+ * Options for creating a SeamHttpWithoutWorkspace client
+ * authenticated with a console session token.
+ */
 export interface SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken extends SeamHttpCommonOptions {
   consoleSessionToken: string
 }
 
+/**
+ * Returns true if the options include a consoleSessionToken.
+ *
+ * @throws {@link SeamHttpInvalidOptionsError} if the consoleSessionToken option
+ * is used with another authentication option.
+ */
 export const isSeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken = (
   options: SeamHttpOptions,
 ): options is SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken => {
@@ -154,11 +223,21 @@ export const isSeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken = (
   return true
 }
 
+/**
+ * Options for creating a SeamHttp client
+ * authenticated with a console session token and scoped to a workspace.
+ */
 export interface SeamHttpOptionsWithConsoleSessionToken extends SeamHttpCommonOptions {
   consoleSessionToken: string
   workspaceId: string
 }
 
+/**
+ * Returns true if the options include a consoleSessionToken and a workspaceId.
+ *
+ * @throws {@link SeamHttpInvalidOptionsError} if the consoleSessionToken option
+ * is used with another authentication option or without the workspaceId option.
+ */
 export const isSeamHttpOptionsWithConsoleSessionToken = (
   options: SeamHttpOptions,
 ): options is SeamHttpOptionsWithConsoleSessionToken => {
@@ -175,10 +254,20 @@ export const isSeamHttpOptionsWithConsoleSessionToken = (
   return true
 }
 
+/**
+ * Options for creating a SeamHttpWithoutWorkspace client
+ * authenticated with a personal access token.
+ */
 export interface SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken extends SeamHttpCommonOptions {
   personalAccessToken: string
 }
 
+/**
+ * Returns true if the options include a personalAccessToken.
+ *
+ * @throws {@link SeamHttpInvalidOptionsError} if the personalAccessToken option
+ * is used with another authentication option.
+ */
 export const isSeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken = (
   options: SeamHttpOptions,
 ): options is SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken => {
@@ -206,11 +295,21 @@ export const isSeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken = (
   return true
 }
 
+/**
+ * Options for creating a SeamHttp client
+ * authenticated with a personal access token and scoped to a workspace.
+ */
 export interface SeamHttpOptionsWithPersonalAccessToken extends SeamHttpCommonOptions {
   personalAccessToken: string
   workspaceId: string
 }
 
+/**
+ * Returns true if the options include a personalAccessToken and a workspaceId.
+ *
+ * @throws {@link SeamHttpInvalidOptionsError} if the personalAccessToken option
+ * is used with another authentication option or without the workspaceId option.
+ */
 export const isSeamHttpOptionsWithPersonalAccessToken = (
   options: SeamHttpOptions,
 ): options is SeamHttpOptionsWithPersonalAccessToken => {
@@ -227,6 +326,9 @@ export const isSeamHttpOptionsWithPersonalAccessToken = (
   return true
 }
 
+/**
+ * Error thrown when a SeamHttp client is created with invalid options.
+ */
 export class SeamHttpInvalidOptionsError extends Error {
   constructor(message: string) {
     super(`SeamHttp received invalid options: ${message}`)
@@ -234,6 +336,9 @@ export class SeamHttpInvalidOptionsError extends Error {
   }
 }
 
+/**
+ * Error thrown when a SeamHttpWithoutWorkspace client is created with invalid options.
+ */
 export class SeamHttpWithoutWorkspaceInvalidOptionsError extends Error {
   constructor(message: string) {
     super(`SeamHttpWithoutWorkspace received invalid options: ${message}`)

package/src/lib/request-options.ts

@@ -1,9 +1,22 @@
 import type { ResolveActionAttemptOptions } from './resolve-action-attempt.js'
 
+/**
+ * Options for how a {@link SeamHttpRequest} is executed.
+ */
 export interface SeamHttpRequestOptions {
+  /**
+   * Controls whether to wait for the action attempt to resolve
+   * when a request returns an action attempt.
+   * Pass a boolean to toggle waiting,
+   * or {@link ResolveActionAttemptOptions} to also configure
+   * the timeout and polling interval.
+   */
   waitForActionAttempt?: boolean | ResolveActionAttemptOptions
 }
 
+/**
+ * Returns true if the key is the name of a {@link SeamHttpRequestOptions} property.
+ */
 export const isSeamHttpRequestOption = (
   key: string,
 ): key is keyof SeamHttpRequestOptions => {

package/src/lib/resolve-action-attempt.ts

@@ -1,14 +1,35 @@
 import type { ActionAttempt } from './resources/action-attempt.js'
 
+/**
+ * Client used to poll action attempts by id, e.g., `SeamHttpActionAttempts`.
+ */
 export interface ActionAttemptsClient {
   get(parameters: { action_attempt_id: string }): PromiseLike<ActionAttempt>
 }
 
+/**
+ * Options for waiting until an action attempt resolves.
+ */
 export interface ResolveActionAttemptOptions {
+  /**
+   * Maximum time in milliseconds to wait for the action attempt to resolve.
+   */
   timeout?: number
+
+  /**
+   * Time in milliseconds to wait between polls of the action attempt.
+   */
   pollingInterval?: number
 }
 
+/**
+ * Polls a pending action attempt until it succeeds, fails, or times out.
+ *
+ * @returns The succeeded action attempt.
+ * @throws {@link SeamActionAttemptFailedError} if the action attempt fails.
+ * @throws {@link SeamActionAttemptTimeoutError} if the action attempt
+ * does not resolve within the timeout.
+ */
 export const resolveActionAttempt = async <T extends ActionAttempt>(
   actionAttempt: T,
   actionAttempts: ActionAttemptsClient,
@@ -59,12 +80,18 @@ const pollActionAttempt = async <T extends ActionAttempt>(
   )
 }
 
+/**
+ * Returns true if the error is a {@link SeamActionAttemptError}.
+ */
 export const isSeamActionAttemptError = <T extends ActionAttempt>(
   error: unknown,
 ): error is SeamActionAttemptError<T> => {
   return error instanceof SeamActionAttemptError
 }
 
+/**
+ * Error relating to an action attempt.
+ */
 export class SeamActionAttemptError<T extends ActionAttempt> extends Error {
   actionAttempt: T
 
@@ -75,15 +102,24 @@ export class SeamActionAttemptError<T extends ActionAttempt> extends Error {
   }
 }
 
+/**
+ * Returns true if the error is a {@link SeamActionAttemptFailedError}.
+ */
 export const isSeamActionAttemptFailedError = <T extends ActionAttempt>(
   error: unknown,
 ): error is SeamActionAttemptFailedError<T> => {
   return error instanceof SeamActionAttemptFailedError
 }
 
+/**
+ * Error thrown when an action attempt fails.
+ */
 export class SeamActionAttemptFailedError<
   T extends ActionAttempt,
 > extends SeamActionAttemptError<T> {
+  /**
+   * Error type returned by the Seam API for the failed action attempt.
+   */
   code: string
 
   constructor(actionAttempt: FailedActionAttempt<T>) {
@@ -93,12 +129,18 @@ export class SeamActionAttemptFailedError<
   }
 }
 
+/**
+ * Returns true if the error is a {@link SeamActionAttemptTimeoutError}.
+ */
 export const isSeamActionAttemptTimeoutError = <T extends ActionAttempt>(
   error: unknown,
 ): error is SeamActionAttemptTimeoutError<T> => {
   return error instanceof SeamActionAttemptTimeoutError
 }
 
+/**
+ * Error thrown when an action attempt does not resolve within the timeout.
+ */
 export class SeamActionAttemptTimeoutError<
   T extends ActionAttempt,
 > extends SeamActionAttemptError<T> {
@@ -120,10 +162,16 @@ const isFailedActionAttempt = <T extends ActionAttempt>(
   actionAttempt: T,
 ): actionAttempt is FailedActionAttempt<T> => actionAttempt.status === 'error'
 
+/**
+ * An action attempt that has succeeded.
+ */
 export type SucceededActionAttempt<T extends ActionAttempt> = T & {
   status: 'success'
 }
 
+/**
+ * An action attempt that has failed.
+ */
 export type FailedActionAttempt<T extends ActionAttempt> = T & {
   status: 'error'
 }

package/src/lib/resources/access-code.ts

@@ -292,6 +292,72 @@ export type AccessCode = {
          */
         is_access_code_error: true
 
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
+        message: string
+      } /**
+     * Seam was unable to issue this access code before its start time, so the recipient may be unable to unlock the device. This usually points to a problem that needs attention, such as an offline or disconnected device. Seam keeps retrying, and this error clears automatically if the access code is eventually issued.
+     */
+    | {
+        /**
+         * Date and time at which Seam created the error.
+         */
+        created_at?: string | undefined
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
+        error_code: 'failed_to_issue'
+
+        /**
+         * Indicates that this is an access code error.
+         */
+        is_access_code_error: true
+
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
+        message: string
+      } /**
+     * Seam was unable to apply this access code's pending mutations to the device, so the code on the device does not match its requested state. Seam keeps retrying, and this error clears automatically once the mutations are applied.
+     */
+    | {
+        /**
+         * Date and time at which Seam created the error.
+         */
+        created_at?: string | undefined
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
+        error_code: 'failed_to_apply_mutations'
+
+        /**
+         * Indicates that this is an access code error.
+         */
+        is_access_code_error: true
+
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
+        message: string
+      } /**
+     * This access code is still active on the device even though its `ends_at` has passed, so the recipient may still be able to unlock the device after their access window ended. Seam is attempting to remove it, and this error clears automatically once the access code is no longer active.
+     */
+    | {
+        /**
+         * Date and time at which Seam created the error.
+         */
+        created_at?: string | undefined
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
+        error_code: 'failed_to_expire'
+
+        /**
+         * Indicates that this is an access code error.
+         */
+        is_access_code_error: true
+
         /**
          * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
          */
@@ -1005,6 +1071,40 @@ export type AccessCode = {
          */
         warning_code: 'delay_in_removing_from_device'
       } /**
+     * Seam has not yet issued this access code, even though its start time is approaching, so access may not be ready when the recipient arrives. Seam is still attempting to issue it, and this warning clears automatically once issuance succeeds.
+     */
+    | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
+        created_at?: string | undefined
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
+        message: string
+
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
+        warning_code: 'delay_in_issuing'
+      } /**
+     * Seam has not yet applied this access code's pending mutations to the device, so the code on the device does not yet match its requested state. Seam is still attempting to apply them, and this warning clears automatically once the mutations are applied.
+     */
+    | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
+        created_at?: string | undefined
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
+        message: string
+
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
+        warning_code: 'delay_in_applying_mutations'
+      } /**
      * Third-party integration detected that may cause access codes to fail.
      */
     | {

package/src/lib/resources/device.ts

@@ -1716,18 +1716,6 @@ export type Device = {
            * Set to true when the device does not support the /dual-setpoints API endpoint.
            */
           dual_setpoints_not_supported?: boolean | undefined
-          /**
-           * Enforced cooling setpoint range in Celsius for a Sensi device, derived from an OutOfRange API error.
-           */
-          enforced_cooling_setpoint_range_celsius?: Array<number> | undefined
-          /**
-           * Enforced heating setpoint range in Celsius for a Sensi device, derived from an OutOfRange API error.
-           */
-          enforced_heating_setpoint_range_celsius?: Array<number> | undefined
-          /**
-           * Legacy combined enforced setpoint range in Celsius for a Sensi device, derived from an OutOfRange API error. Read as a fallback for the per-mode ranges below; no longer written.
-           */
-          enforced_setpoint_range_celsius?: Array<number> | undefined
           /**
            * Product type for a Sensi device.
            */

package/src/lib/resources/unmanaged-access-code.ts

@@ -298,6 +298,72 @@ export type UnmanagedAccessCode = {
          */
         is_access_code_error: true
 
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
+        message: string
+      } /**
+     * Seam was unable to issue this access code before its start time, so the recipient may be unable to unlock the device. This usually points to a problem that needs attention, such as an offline or disconnected device. Seam keeps retrying, and this error clears automatically if the access code is eventually issued.
+     */
+    | {
+        /**
+         * Date and time at which Seam created the error.
+         */
+        created_at?: string | undefined
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
+        error_code: 'failed_to_issue'
+
+        /**
+         * Indicates that this is an access code error.
+         */
+        is_access_code_error: true
+
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
+        message: string
+      } /**
+     * Seam was unable to apply this access code's pending mutations to the device, so the code on the device does not match its requested state. Seam keeps retrying, and this error clears automatically once the mutations are applied.
+     */
+    | {
+        /**
+         * Date and time at which Seam created the error.
+         */
+        created_at?: string | undefined
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
+        error_code: 'failed_to_apply_mutations'
+
+        /**
+         * Indicates that this is an access code error.
+         */
+        is_access_code_error: true
+
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
+        message: string
+      } /**
+     * This access code is still active on the device even though its `ends_at` has passed, so the recipient may still be able to unlock the device after their access window ended. Seam is attempting to remove it, and this error clears automatically once the access code is no longer active.
+     */
+    | {
+        /**
+         * Date and time at which Seam created the error.
+         */
+        created_at?: string | undefined
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
+        error_code: 'failed_to_expire'
+
+        /**
+         * Indicates that this is an access code error.
+         */
+        is_access_code_error: true
+
         /**
          * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
          */
@@ -787,6 +853,40 @@ export type UnmanagedAccessCode = {
          */
         warning_code: 'delay_in_removing_from_device'
       } /**
+     * Seam has not yet issued this access code, even though its start time is approaching, so access may not be ready when the recipient arrives. Seam is still attempting to issue it, and this warning clears automatically once issuance succeeds.
+     */
+    | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
+        created_at?: string | undefined
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
+        message: string
+
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
+        warning_code: 'delay_in_issuing'
+      } /**
+     * Seam has not yet applied this access code's pending mutations to the device, so the code on the device does not yet match its requested state. Seam is still attempting to apply them, and this warning clears automatically once the mutations are applied.
+     */
+    | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
+        created_at?: string | undefined
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
+        message: string
+
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
+        warning_code: 'delay_in_applying_mutations'
+      } /**
      * Third-party integration detected that may cause access codes to fail.
      */
     | {

package/src/lib/routes/events/events.ts

@@ -318,6 +318,12 @@ export type EventsListParameters = RequireAtLeastOne<{
     | 'access_code.removed_from_device'
     | 'access_code.delay_in_setting_on_device'
     | 'access_code.failed_to_set_on_device'
+    | 'access_code.issued'
+    | 'access_code.delay_in_issuing'
+    | 'access_code.failed_to_issue'
+    | 'access_code.delay_in_applying_mutations'
+    | 'access_code.failed_to_apply_mutations'
+    | 'access_code.failed_to_expire'
     | 'access_code.deleted'
     | 'access_code.delay_in_removing_from_device'
     | 'access_code.failed_to_remove_from_device'
@@ -433,6 +439,12 @@ export type EventsListParameters = RequireAtLeastOne<{
         | 'access_code.removed_from_device'
         | 'access_code.delay_in_setting_on_device'
         | 'access_code.failed_to_set_on_device'
+        | 'access_code.issued'
+        | 'access_code.delay_in_issuing'
+        | 'access_code.failed_to_issue'
+        | 'access_code.delay_in_applying_mutations'
+        | 'access_code.failed_to_apply_mutations'
+        | 'access_code.failed_to_expire'
         | 'access_code.deleted'
         | 'access_code.delay_in_removing_from_device'
         | 'access_code.failed_to_remove_from_device'