@seamapi/http 2.0.0 → 2.2.0

package/lib/seam/connect/resources/batch.d.ts

@@ -48,6 +48,9 @@ interface BatchResourceMap {
     user_identities: UserIdentity;
     workspaces: Workspace;
 }
+/**
+ * A batch of workspace resources.
+ */
 export type Batch<TKey extends keyof BatchResourceMap = keyof BatchResourceMap> = {
     [K in TKey]?: Array<BatchResourceMap[K]> | undefined;
 };

package/lib/seam/connect/resources/client-session.d.ts

@@ -1,14 +1,62 @@
+/**
+ * Represents a [client session](https://docs.seam.co/core-concepts/authentication/client-session-tokens). If you want to restrict your users' access to their own devices, use client sessions.
+ *
+ * You create each client session with a custom `user_identifier_key`. Normally, the `user_identifier_key` is a user ID that your application provides.
+ *
+ * When calling the Seam API from your backend using an API key, you can pass the `user_identifier_key` as a parameter to limit results to the associated client session. For example, `/devices/list?user_identifier_key=123` only returns devices associated with the client session created with the `user_identifier_key` `123`.
+ *
+ * A client session has a token that you can use with the Seam JavaScript SDK to make requests from the client (browser) directly to the Seam API. The token restricts the user's access to only the devices that they own.
+ *
+ * See also [Get Started with React](https://docs.seam.co/ui-components/overview/getting-started-with-seam-components/get-started-with-react-components-and-client-session-tokens).
+ */
 export type ClientSession = {
+    /**
+     * ID of the client session.
+     */
     client_session_id: string;
+    /**
+     * IDs of the [Connect Webviews](https://docs.seam.co/core-concepts/connect-webviews) associated with the [client session](https://docs.seam.co/core-concepts/authentication/client-session-tokens).
+     */
     connect_webview_ids: Array<string>;
+    /**
+     * IDs of the [connected accounts](https://docs.seam.co/core-concepts/connected-accounts) associated with the [client session](https://docs.seam.co/core-concepts/authentication/client-session-tokens).
+     */
     connected_account_ids: Array<string>;
+    /**
+     * Date and time at which the [client session](https://docs.seam.co/core-concepts/authentication/client-session-tokens) was created.
+     */
     created_at: string;
+    /**
+     * Customer key associated with the [client session](https://docs.seam.co/core-concepts/authentication/client-session-tokens).
+     */
     customer_key?: string | undefined;
+    /**
+     * Number of devices associated with the [client session](https://docs.seam.co/core-concepts/authentication/client-session-tokens).
+     */
     device_count: number;
+    /**
+     * Date and time at which the [client session](https://docs.seam.co/core-concepts/authentication/client-session-tokens) expires.
+     */
     expires_at: string;
+    /**
+     * Client session token associated with the [client session](https://docs.seam.co/core-concepts/authentication/client-session-tokens).
+     */
     token: string;
+    /**
+     * Your user ID for the user associated with the [client session](https://docs.seam.co/core-concepts/authentication/client-session-tokens).
+     */
     user_identifier_key: string | null;
+    /**
+     * ID of the [user identity](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) associated with the client session.
+     */
     user_identity_id?: string | undefined;
+    /**
+     * IDs of the [user identities](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) associated with the client session.
+     * @deprecated Use `user_identity_id` instead.
+     */
     user_identity_ids: Array<string>;
+    /**
+     * ID of the workspace associated with the client session.
+     */
     workspace_id: string;
 };

package/lib/seam/connect/resources/connect-webview.d.ts

@@ -1,21 +1,91 @@
+/**
+ * Represents a [Connect Webview](https://docs.seam.co/core-concepts/connect-webviews).
+ *
+ * Connect Webviews are fully-embedded client-side components that you add to your app. Your users interact with your embedded Connect Webviews to link their IoT device or system accounts to Seam. That is, Connect Webviews walk your users through the process of logging in to their device or system accounts. Seam handles all the authentication steps, and—once your user has completed the authorization through your app—you can access and control their devices or systems using the Seam API.
+ *
+ * Connect Webviews perform credential validation, multifactor authentication (when applicable), and error handling for each brand that Seam supports. Further, Connect Webviews work across all modern browsers and platforms, including Chrome, Safari, and Firefox.
+ *
+ * To enable a user to connect their device or system account to Seam through your app, first create a `connect_webview`. Once created, this `connect_webview` includes a URL that you can use to open an [iframe](https://www.w3schools.com/html/html_iframe.asp) or new window containing the Connect Webview for your user.
+ *
+ * When you create a Connect Webview, specify the desired provider category key in the `provider_category` parameter. Alternately, to specify a list of providers explicitly, use the `accepted_providers` parameter with a list of device provider keys.
+ *
+ * To list all providers within a category, use `/devices/list_device_providers` with the desired `provider_category` filter. To list all provider keys, use `/devices/list_device_providers` with no filters.
+ */
 export type ConnectWebview = {
+    /**
+     * High-level device capabilities that the Connect Webview can accept. When creating a Connect Webview, you can specify the types of devices that it can connect to Seam. If you do not set custom `accepted_capabilities`, Seam uses a default set of `accepted_capabilities` for each provider. For example, if you create a Connect Webview that accepts SmartThing devices, without specifying `accepted_capabilities`, Seam accepts only SmartThings locks. To connect SmartThings thermostats and locks to Seam, create a Connect Webview and include both `thermostat` and `lock` in the `accepted_capabilities`.
+     */
     accepted_capabilities: Array<'lock' | 'thermostat' | 'noise_sensor' | 'access_control' | 'camera'>;
+    /**
+     * List of accepted [provider keys](https://docs.seam.co/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).
+     */
     accepted_providers: Array<string>;
+    /**
+     * Indicates whether any provider is allowed.
+     */
     any_provider_allowed: boolean;
+    /**
+     * Date and time at which the user authorized (through the Connect Webview) the management of their devices.
+     */
     authorized_at: string | null;
+    /**
+     * Indicates whether Seam should [import all new devices](https://docs.seam.co/core-concepts/connect-webviews/customizing-connect-webviews#automatically_manage_new_devices) for the connected account to make these devices available for use and management by the Seam API.
+     */
     automatically_manage_new_devices: boolean;
+    /**
+     * ID of the Connect Webview.
+     */
     connect_webview_id: string;
+    /**
+     * ID of the connected account associated with the Connect Webview.
+     */
     connected_account_id: string | null;
+    /**
+     * Date and time at which the Connect Webview was created.
+     */
     created_at: string;
+    /**
+     * Set of key:value pairs. Adding custom metadata to a resource, such as a [Connect Webview](https://docs.seam.co/core-concepts/connect-webviews/attaching-custom-data-to-the-connect-webview), [connected account](https://docs.seam.co/core-concepts/connected-accounts/adding-custom-metadata-to-a-connected-account), or [device](https://docs.seam.co/core-concepts/devices/adding-custom-metadata-to-a-device), enables you to store custom information, like customer details or internal IDs from your application.
+     */
     custom_metadata: Record<string, unknown>;
+    /**
+     * URL to which the Connect Webview should redirect when an unexpected error occurs.
+     */
     custom_redirect_failure_url: string | null;
+    /**
+     * URL to which the Connect Webview should redirect when the user successfully pairs a device or system. If you do not set the `custom_redirect_failure_url`, the Connect Webview redirects to the `custom_redirect_url` when an unexpected error occurs.
+     */
     custom_redirect_url: string | null;
+    /**
+     * The customer key associated with this webview, if any.
+     */
     customer_key?: string | undefined;
+    /**
+     * Device selection mode of the Connect Webview. Supported values: `none`, `single`, `multiple`.
+     */
     device_selection_mode: 'none' | 'single' | 'multiple';
+    /**
+     * Indicates whether the user logged in successfully using the Connect Webview.
+     */
     login_successful: boolean;
+    /**
+     * Selected provider of the Connect Webview, one of the [provider keys](https://docs.seam.co/core-concepts/connect-webviews/customizing-connect-webviews#customize-the-brands-to-display-in-your-connect-webviews).
+     */
     selected_provider: string | null;
+    /**
+     * Status of the Connect Webview. `authorized` indicates that the user has successfully logged into their device or system account, thereby completing the Connect Webview.
+     */
     status: 'pending' | 'failed' | 'authorized';
+    /**
+     * URL for the Connect Webview. You use the URL to display the Connect Webview flow to your user.
+     */
     url: string;
+    /**
+     * Indicates whether Seam should [finish syncing all devices](https://docs.seam.co/core-concepts/connect-webviews/customizing-connect-webviews#wait_for_device_creation) in a newly-connected account before completing the associated Connect Webview.
+     */
     wait_for_device_creation: boolean;
+    /**
+     * ID of the workspace that contains the Connect Webview.
+     */
     workspace_id: string;
 };

package/lib/seam/connect/resources/connected-account.d.ts

@@ -1,98 +1,367 @@
+/**
+ * Represents a [connected account](https://docs.seam.co/core-concepts/connected-accounts). A connected account is an external third-party account to which your user has authorized Seam to get access, for example, an August account with a list of door locks.
+ */
 export type ConnectedAccount = {
+    /**
+     * List of capabilities that were accepted during the account connection process.
+     */
     accepted_capabilities: Array<'lock' | 'thermostat' | 'noise_sensor' | 'access_control' | 'camera'>;
+    /**
+     * Type of connected account.
+     */
     account_type?: string | undefined;
+    /**
+     * Display name for the connected account type.
+     */
     account_type_display_name: string;
+    /**
+     * Indicates whether Seam should [import all new devices](https://docs.seam.co/core-concepts/connect-webviews/customizing-connect-webviews#automatically_manage_new_devices) for the connected account to make these devices available for management by the Seam API.
+     */
     automatically_manage_new_devices: boolean;
+    /**
+     * ID of the connected account.
+     */
     connected_account_id: string;
+    /**
+     * Date and time at which the connected account was created.
+     */
     created_at?: string | undefined;
+    /**
+     * Set of key:value pairs. Adding custom metadata to a resource, such as a [Connect Webview](https://docs.seam.co/core-concepts/connect-webviews/attaching-custom-data-to-the-connect-webview), [connected account](https://docs.seam.co/core-concepts/connected-accounts/adding-custom-metadata-to-a-connected-account), or [device](https://docs.seam.co/core-concepts/devices/adding-custom-metadata-to-a-device), enables you to store custom information, like customer details or internal IDs from your application.
+     */
     custom_metadata: Record<string, unknown>;
+    /**
+     * Your unique key for the customer associated with this connected account.
+     */
     customer_key?: string | undefined;
+    /**
+     * Default reservation check-in time for this connected account, as `HH:mm` (24-hour). Sourced from the connector configuration — set during the connect_webview for providers like Lodgify whose API does not expose check-in times.
+     */
     default_checkin_time?: string | undefined;
+    /**
+     * Default reservation check-out time for this connected account, as `HH:mm` (24-hour). Sourced from the connector configuration.
+     */
     default_checkout_time?: string | undefined;
+    /**
+     * Display name for the connected account.
+     */
     display_name: string;
-    errors: Array<{
+    /**
+     * Errors associated with the connected account.
+     */
+    errors: Array<
+    /**
+     * Indicates that the account is disconnected.
+     */
+    {
+        /**
+         * Date and time at which Seam created the error.
+         */
         created_at: string;
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
         error_code: 'account_disconnected';
+        /**
+         * Indicates whether the error is related to [Seam Bridge](https://docs.seam.co/capability-guides/seam-bridge).
+         */
         is_bridge_error?: boolean | undefined;
+        /**
+         * Indicates whether the error is related specifically to the connected account.
+         */
         is_connected_account_error?: boolean | undefined;
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
-    } | {
+    } /**
+   * Indicates that the Seam API cannot communicate with [Seam Bridge](https://docs.seam.co/capability-guides/seam-bridge), for example, if the Seam Bridge executable has stopped or if the computer running the Seam Bridge executable is offline. See also [Troubleshooting Your Access Control System](https://docs.seam.co/low-level-apis/access-systems/troubleshooting-your-access-control-system#acs_system-errors-seam_bridge_disconnected).
+   */ | {
+        /**
+         * Date and time at which Seam created the error.
+         */
         created_at: string;
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
         error_code: 'bridge_disconnected';
+        /**
+         * Indicates whether the error is related to [Seam Bridge](https://docs.seam.co/capability-guides/seam-bridge).
+         */
         is_bridge_error?: boolean | undefined;
+        /**
+         * Indicates whether the error is related specifically to the connected account.
+         */
         is_connected_account_error?: boolean | undefined;
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
-    } | {
+    } /**
+   * Indicates that the maximum number of users allowed for the site has been reached. This means that new access codes cannot be created. Contact Salto support to increase the user limit.
+   */ | {
+        /**
+         * Date and time at which Seam created the error.
+         */
         created_at: string;
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
         error_code: 'salto_ks_subscription_limit_exceeded';
+        /**
+         * Indicates whether the error is related to [Seam Bridge](https://docs.seam.co/capability-guides/seam-bridge).
+         */
         is_bridge_error?: boolean | undefined;
+        /**
+         * Indicates whether the error is related specifically to the connected account.
+         */
         is_connected_account_error?: boolean | undefined;
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * Salto KS metadata associated with the connected account that has an error.
+         */
         salto_ks_metadata: {
+            /**
+             * Salto sites associated with the connected account that has an error.
+             */
             sites?: Array<{
+                /**
+                 * ID of a Salto site associated with the connected account that has an error.
+                 */
                 site_id?: string | undefined;
+                /**
+                 * Name of a Salto site associated with the connected account that has an error.
+                 */
                 site_name?: string | undefined;
+                /**
+                 * Subscription limit of site users for a Salto site associated with the connected account that has an error.
+                 */
                 site_user_subscription_limit?: number | undefined;
+                /**
+                 * Count of subscribed site users for a Salto site associated with the connected account that has an error.
+                 */
                 subscribed_site_user_count?: number | undefined;
             }> | undefined;
         };
-    } | {
+    } /**
+   * Indicates that one or more dormakaba sites associated with the connected account could not be connected. Contact dormakaba support.
+   */ | {
+        /**
+         * Date and time at which Seam created the error.
+         */
         created_at: string;
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
         error_code: 'dormakaba_sites_disconnected';
+        /**
+         * Indicates whether the error is related to [Seam Bridge](https://docs.seam.co/capability-guides/seam-bridge).
+         */
         is_bridge_error?: boolean | undefined;
+        /**
+         * Indicates whether the error is related specifically to the connected account.
+         */
         is_connected_account_error?: boolean | undefined;
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
     }>;
+    /**
+     * For iCal connected accounts, the platform that produced the feed (for example, `airbnb`, `vrbo`, or `booking`), or `unknown` when it could not be determined. Intended for rendering the source platform's logo.
+     */
     ical_feed_origin?: string | undefined;
+    /**
+     * For iCal connected accounts, the feed URL for the connection. Sourced from the connector configuration.
+     */
     ical_url?: string | undefined;
+    /**
+     * Logo URL for the connected account provider.
+     */
     image_url?: string | undefined;
+    /**
+     * IANA time zone (e.g. America/Los_Angeles) for this connected account. Sourced from the connector configuration.
+     */
     time_zone?: string | undefined;
+    /**
+     * User identifier associated with the connected account.
+     * @deprecated Use `display_name` instead.
+     */
     user_identifier?: {
+        /**
+         * API URL for the user identifier associated with the connected account.
+         */
         api_url?: string | undefined;
+        /**
+         * Email address of the user identifier associated with the connected account.
+         */
         email?: string | undefined;
+        /**
+         * Indicates whether the user identifier associated with the connected account is exclusive.
+         */
         exclusive?: boolean | undefined;
+        /**
+         * Phone number of the user identifier associated with the connected account.
+         */
         phone?: string | undefined;
+        /**
+         * Username of the user identifier associated with the connected account.
+         */
         username?: string | undefined;
     } | undefined;
-    warnings: Array<{
+    /**
+     * Warnings associated with the connected account.
+     */
+    warnings: Array<
+    /**
+     * Indicates that scheduled downtime is planned for the connected account.
+     */
+    {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * 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: 'scheduled_maintenance_window';
-    } | {
+    } /**
+   * Indicates that an unknown issue occurred while syncing the state of the connected account with the provider. This issue may affect the proper functioning of one or more resources in the account.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * 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: 'unknown_issue_with_connected_account';
-    } | {
+    } /**
+   * Indicates that the Salto KS site has exceeded 80% of the maximum number of allowed users. Increase your subscription limit or delete some users from your site.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * Salto KS metadata associated with the connected account that has a warning.
+         */
         salto_ks_metadata: {
+            /**
+             * Salto sites associated with the connected account that has a warning.
+             */
             sites?: Array<{
+                /**
+                 * ID of a Salto site associated with the connected account that has a warning.
+                 */
                 site_id?: string | undefined;
+                /**
+                 * Name of a Salto site associated with the connected account that has a warning.
+                 */
                 site_name?: string | undefined;
+                /**
+                 * Subscription limit of site users for a Salto site associated with the connected account that has a warning.
+                 */
                 site_user_subscription_limit?: number | undefined;
+                /**
+                 * Count of subscribed site users for a Salto site associated with the connected account that has a warning.
+                 */
                 subscribed_site_user_count?: number | undefined;
             }> | undefined;
         };
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'salto_ks_subscription_limit_almost_reached';
-    } | {
+    } /**
+   * Indicates that the Connected Account requires reauthorization using a new Connect Webview. The account is still connected, but cannot access new features. Delaying reauthorization too long will eventually cause the Connected Account to become disconnected.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * 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: 'account_reauthorization_requested';
-    } | {
+    } /**
+   * Indicates that the connected account is currently being deleted. All devices, access codes, and other resources associated with this account are in the process of being removed from Seam.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * 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: 'being_deleted';
-    } | {
+    } /**
+   * Indicates that the connected account's provider service is temporarily unavailable. Seam will automatically retry and reconnect when the service becomes available again.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * 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: 'provider_service_unavailable';
-    } | {
+    } /**
+   * Indicates that the connected account requires additional setup before it can be fully operational. Follow the instructions in the warning message to complete the setup.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * 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: 'setup_required';
-    } | {
+    } /**
+   * Indicates that one or more dormakaba sites associated with the connected account are not approved. Contact support@getseam.com to finish setting up your account.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * 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: 'dormakaba_sites_unapproved';
     }>;
 };

package/lib/seam/connect/resources/customer-portal.d.ts

@@ -1,7 +1,29 @@
+/**
+ * Represents a Customer Portal. Customer Portal is a hosted, customizable interface for managing device access. It enables you to embed secure, pre-authenticated access flows into your product—either by sharing a link with users or embedding a view in an iframe.
+ *
+ * With Customer Portal, you no longer need to build out frontend experiences for physical access, thermostats, and sensors. Instead, you can ship enterprise-grade access control experiences in a fraction of the time, while maintaining your product's branding and user experience.
+ *
+ * Seam hosts these flows, handling everything from account connection and device mapping to full-featured device control.
+ */
 export type CustomerPortal = {
+    /**
+     * Date and time at which the customer portal link was created.
+     */
     created_at: string;
+    /**
+     * Customer key for the customer portal.
+     */
     customer_key: string;
+    /**
+     * Date and time at which the customer portal link expires.
+     */
     expires_at: string;
+    /**
+     * URL for the customer portal.
+     */
     url: string;
+    /**
+     * ID of the workspace associated with the customer portal.
+     */
     workspace_id: string;
 };