@seamapi/http 2.18.0 → 2.19.0

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/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/seam-http-error.ts

@@ -1,9 +1,25 @@
 import type { ApiError } from './api-error-types.js'
 
+/**
+ * Error thrown when the Seam API returns an error response.
+ */
 export class SeamHttpApiError extends Error {
+  /**
+   * Error type returned by the Seam API, e.g., `invalid_input`.
+   */
   code: string
+
   statusCode: number
+
+  /**
+   * Unique identifier of the request that failed.
+   * Provide this to Seam support when reporting an issue.
+   */
   requestId: string
+
+  /**
+   * Additional error-specific data returned by the Seam API, if any.
+   */
   data?: unknown
 
   constructor(error: ApiError, statusCode: number, requestId: string) {
@@ -17,12 +33,18 @@ export class SeamHttpApiError extends Error {
   }
 }
 
+/**
+ * Returns true if the error is a {@link SeamHttpApiError}.
+ */
 export const isSeamHttpApiError = (
   error: unknown,
 ): error is SeamHttpApiError => {
   return error instanceof SeamHttpApiError
 }
 
+/**
+ * Error thrown when the Seam API returns a 401 Unauthorized error response.
+ */
 export class SeamHttpUnauthorizedError extends SeamHttpApiError {
   override code: 'unauthorized'
   override statusCode: 401
@@ -38,14 +60,21 @@ export class SeamHttpUnauthorizedError extends SeamHttpApiError {
   }
 }
 
+/**
+ * Returns true if the error is a {@link SeamHttpUnauthorizedError}.
+ */
 export const isSeamHttpUnauthorizedError = (
   error: unknown,
 ): error is SeamHttpUnauthorizedError => {
   return error instanceof SeamHttpUnauthorizedError
 }
 
+/**
+ * Error thrown when the Seam API returns an `invalid_input` error response.
+ */
 export class SeamHttpInvalidInputError extends SeamHttpApiError {
   override code: 'invalid_input'
+
   readonly #validationErrors: NonNullable<ApiError['validation_errors']>
 
   constructor(error: ApiError, statusCode: number, requestId: string) {
@@ -55,11 +84,20 @@ export class SeamHttpInvalidInputError extends SeamHttpApiError {
     this.#validationErrors = error.validation_errors ?? {}
   }
 
+  /**
+   * Returns the validation error messages for the request parameter,
+   * or an empty array if the parameter had no validation errors.
+   *
+   * @param paramName - Name of the request parameter.
+   */
   getValidationErrorMessages(paramName: string): string[] {
     return this.#validationErrors[paramName]?._errors ?? []
   }
 }
 
+/**
+ * Returns true if the error is a {@link SeamHttpInvalidInputError}.
+ */
 export const isSeamHttpInvalidInputError = (
   error: unknown,
 ): error is SeamHttpInvalidInputError => {

package/src/lib/seam-http-request.ts

@@ -29,6 +29,20 @@ interface SeamHttpRequestConfig<TResponseKey> {
   readonly requiredParameterNames?: readonly string[]
 }
 
+/**
+ * A lazy request to the Seam API.
+ *
+ * Creating a SeamHttpRequest does not send anything over the network.
+ * The request is sent once `execute` is called,
+ * or when the request is awaited like a Promise,
+ * e.g., with `await`, `then`, `catch`, or `finally`.
+ * When the response contains an action attempt,
+ * awaiting the request also waits for the action attempt to resolve
+ * according to the `waitForActionAttempt` option.
+ *
+ * Before sending, the request may be inspected
+ * with `url`, `pathname`, `method`, `params`, and `body`.
+ */
 export class SeamHttpRequest<
   const TResponse,
   const TResponseKey extends keyof TResponse | undefined,
@@ -48,6 +62,10 @@ export class SeamHttpRequest<
     this.#config = config
   }
 
+  /**
+   * The key of the API response object containing the response data,
+   * or undefined if the endpoint returns an empty response.
+   */
   public get responseKey(): TResponseKey {
     return this.#config.responseKey
   }
@@ -56,6 +74,9 @@ export class SeamHttpRequest<
     return this.#config.hasPagination ?? false
   }
 
+  /**
+   * The full request URL including any serialized query parameters.
+   */
   public get url(): URL {
     const { client } = this.#parent
 
@@ -92,6 +113,12 @@ export class SeamHttpRequest<
     return this.#config.body
   }
 
+  /**
+   * Sends the request and returns the response data.
+   * If the response contains an action attempt,
+   * waits for the action attempt to resolve
+   * according to the `waitForActionAttempt` option.
+   */
   async execute(): Promise<
     TResponseKey extends keyof TResponse ? TResponse[TResponseKey] : undefined
   > {
@@ -130,6 +157,10 @@ export class SeamHttpRequest<
     return data
   }
 
+  /**
+   * Sends the request and returns the entire response body
+   * without waiting for any action attempt to resolve.
+   */
   async fetchResponse(): Promise<TResponse> {
     assertValidRequestParameters(
       this.#config.parameters,

package/src/lib/seam-paginator.ts

@@ -9,6 +9,9 @@ interface SeamPaginatorParent {
 
 declare const $brand: unique symbol
 
+/**
+ * Opaque cursor identifying a page of results returned by the Seam API.
+ */
 export type SeamPageCursor = string & { [$brand]: 'SeamPageCursor' }
 
 interface Pagination {
@@ -17,6 +20,15 @@ interface Pagination {
   readonly nextPageUrl: string | null
 }
 
+/**
+ * Iterates over paginated results from Seam API list endpoints.
+ *
+ * Create a SeamPaginator with the client's `createPaginator` method.
+ * Fetch pages manually with `firstPage` and `nextPage`,
+ * iterate over pages with `for await`,
+ * iterate over items across all pages with `flatten`,
+ * or collect every item into a single array with `flattenToArray`.
+ */
 export class SeamPaginator<
   const TResponse,
   const TResponseKey extends keyof TResponse,
@@ -37,12 +49,19 @@ export class SeamPaginator<
     this.#request = request
   }
 
+  /**
+   * Fetches the first page of results along with the pagination state.
+   */
   async firstPage(): Promise<
     [EnsureReadonlyArray<TResponse[TResponseKey]>, Pagination]
   > {
     return await this.#fetch()
   }
 
+  /**
+   * Fetches the next page of results
+   * using the nextPageCursor returned with a previous page.
+   */
   async nextPage(
     nextPageCursor: Pagination['nextPageCursor'],
   ): Promise<[EnsureReadonlyArray<TResponse[TResponseKey]>, Pagination]> {
@@ -104,6 +123,9 @@ export class SeamPaginator<
     ] as const
   }
 
+  /**
+   * Fetches every page and returns all items in a single array.
+   */
   async flattenToArray(): Promise<
     EnsureReadonlyArray<TResponse[TResponseKey]>
   > {
@@ -117,6 +139,9 @@ export class SeamPaginator<
     return items as EnsureReadonlyArray<TResponse[TResponseKey]>
   }
 
+  /**
+   * Yields each item across all pages, fetching the next page as needed.
+   */
   async *flatten(): AsyncGenerator<
     EnsureReadonlyArray<TResponse[TResponseKey]>
   > {
@@ -132,6 +157,9 @@ export class SeamPaginator<
     }
   }
 
+  /**
+   * Yields each page of items, fetching the next page as needed.
+   */
   async *[Symbol.asyncIterator](): AsyncGenerator<
     EnsureReadonlyArray<TResponse[TResponseKey]>
   > {

package/src/lib/version.ts

@@ -1,3 +1,3 @@
-const seamapiJavascriptHttpVersion = '2.18.0'
+const seamapiJavascriptHttpVersion = '2.19.0'
 
 export default seamapiJavascriptHttpVersion