@seamapi/types 1.399.0 → 1.400.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamapi/types",
-  "version": "1.399.0",
+  "version": "1.400.0",
   "description": "TypeScript types for the Seam API.",
   "type": "module",
   "main": "index.js",

package/src/lib/seam/connect/models/access-codes/managed-access-code.ts

@@ -532,7 +532,13 @@ export const access_code = z.object({
     .string()
     .nullable()
     .describe(
-      'Name of the access code. Enables administrators and users to identify the access code easily, especially when there are numerous access codes.',
+      `Name of the access code. Enables administrators and users to identify the access code easily, especially when there are numerous access codes.
+      
+      Note that the name provided on Seam is used to identify the code on Seam and is not necessarily the name that will appear in the lock provider's app or on the device. This is because lock providers may have constraints on names, such as length, uniqueness, or characters that can be used. In addition, some lock providers may break down names into components such as \`first_name\` and \`last_name\`.
+      
+      To provide a consistent experience, Seam identifies the code on Seam by its name but may modify the name that appears on the lock provider's app or on the device. For example, Seam may add additional characters or truncate the name to meet provider constraints.
+      
+      To help your users identify codes set by Seam, Seam provides the name exactly as it appears on the lock provider's app or on the device as a separate property called \`appearance\`. This is an object with a \`name\` property and, optionally, \`first_name\` and \`last_name\` properties (for providers that break down a name into components).`,
     ),
   code: z
     .string()
@@ -623,7 +629,7 @@ export const access_code = z.object({
 
   An access code is a code used for a keypad or pinpad device. Unlike physical keys, which can easily be lost or duplicated, PIN codes can be customized, tracked, and altered on the fly. Using the Seam Access Code API, you can easily generate access codes on the hundreds of door lock models with which we integrate.
 
-  Seam supports programming two types of access codes: [ongoing](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes#ongoing-access-codes) and [time-bound](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes#time-bound-access-codes). To differentiate between the two, refer to the \`type\` property of the access code. Ongoing codes display as \`ongoing\`, whereas time-bound codes are labeled \`time_bound\`.
+  Seam supports programming two types of access codes: [ongoing](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes#ongoing-access-codes) and [time-bound](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes#time-bound-access-codes). To differentiate between the two, refer to the \`type\` property of the access code. Ongoing codes display as \`ongoing\`, whereas time-bound codes are labeled \`time_bound\`. An ongoing access code is active, until it has been removed from the device. To specify an ongoing access code, leave both \`starts_at\` and \`ends_at\` empty. A time-bound access code will be programmed at the \`starts_at\` time and removed at the \`ends_at\` time.
 
   In addition, for certain devices, Seam also supports [offline access codes](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes#offline-access-codes). Offline access (PIN) codes are designed for door locks that might not always maintain an internet connection. For this type of access code, the device manufacturer uses encryption keys (tokens) to create server-based registries of algorithmically-generated offline PIN codes. Because the tokens remain synchronized with the managed devices, the locks do not require an active internet connection—and you do not need to be near the locks—to create an offline access code. Then, owners or managers can share these offline codes with users through a variety of mechanisms, such as messaging applications. That is, lock users do not need to install a smartphone application to receive an offline access code.
 `)

package/src/lib/seam/connect/models/access-codes/unmanaged-access-code.ts

@@ -36,6 +36,10 @@ export const unmanaged_access_code = access_code
     When you create an access code on a device in Seam, it is created as a managed access code. Access codes that exist on a device that were not created through Seam are considered unmanaged codes. We strictly limit the operations that can be performed on unmanaged codes.
 
     Prior to using Seam to manage your devices, you may have used another lock management system to manage the access codes on your devices. Where possible, we help you keep any existing access codes on devices and transition those codes to ones managed by your Seam workspace.
+
+    Not all providers support unmanaged access codes. The following providers do not support unmanaged access codes:
+    
+    - [Kwikset](https://docs.seam.co/latest/device-and-system-integration-guides/kwikset-locks)
   `)
 
 export type UnmanagedAccessCode = z.infer<typeof unmanaged_access_code>

package/src/lib/seam/connect/models/client-sessions/client-session.ts

@@ -15,6 +15,15 @@ export const client_session = z.object({
   ---
   route_path: /client_sessions
   ---
+  Represents a [client session](https://docs.seam.co/latest/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/latest/ui-components/overview/getting-started-with-seam-components/get-started-with-react-components-and-client-session-tokens).
 `)
 
 export type ClientSession = z.infer<typeof client_session>

package/src/lib/seam/connect/models/connect-webviews/connect-webview.ts

@@ -22,6 +22,7 @@ export const connect_webview = z.object({
   accepted_devices: z.array(z.string()).describe(
     `
       ---
+      undocumented: Unused. Will be removed.
       deprecated: Unused. Will be removed.
       ---
       `,
@@ -29,6 +30,7 @@ export const connect_webview = z.object({
   any_device_allowed: z.boolean().describe(
     `
       ---
+      undocumented: Unused. Will be removed.
       deprecated: Unused. Will be removed.
       ---
       `,
@@ -48,6 +50,17 @@ export const connect_webview = z.object({
   ---
   route_path: /connect_webviews
   ---
+  Represents a [Connect Webview](https://docs.seam.co/latest/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 = z.infer<typeof connect_webview>

package/src/lib/seam/connect/models/connected-accounts/connected-account.ts

@@ -178,6 +178,7 @@ export const connected_account = z.object({
   ---
   route_path: /connected_accounts
   ---
+  Represents a [connected account](https://docs.seam.co/latest/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 = z.infer<typeof connected_account>

package/src/lib/seam/connect/models/devices/capability-properties/access-code.ts

@@ -32,7 +32,12 @@ export const access_code_capability_properties = z.object({
   _experimental_supported_code_from_access_codes_lengths: z
     .array(z.number())
     .optional(),
-  code_constraints: z.array(access_code_constraint).optional(),
+  code_constraints: z
+    .array(access_code_constraint)
+    .optional()
+    .describe(
+      'Constraints on access codes for the device. Seam represents each constraint as an object with a `constraint_type` property. Depending on the constraint type, there may also be additional properties. Note that some constraints are manufacturer- or device-specific.',
+    ),
   supported_code_lengths: z.array(z.number()).optional(),
   max_active_codes_supported: z.number().optional(),
   supports_backup_access_code_pool: z.boolean().optional(),

package/src/lib/seam/connect/models/devices/device.ts

@@ -483,7 +483,12 @@ export const common_device_properties = z.object({
       'Represents the current status of the battery charge level. Values are "critical," which indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging; "low," which signifies that the battery is under the preferred threshold and should be charged soon; "good," which denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging; and "full," which represents a battery that is fully charged, providing the maximum duration of usage.',
     ),
   // todo: use enum
-  manufacturer: z.string().optional().describe('Manufacturer of the device.'),
+  manufacturer: z
+    .string()
+    .optional()
+    .describe(
+      'Manufacturer of the device. When a device, such as a smart lock, is connected through a smart hub, the manufacturer of the device might be different from that of the smart hub.',
+    ),
   image_url: z.string().url().optional().describe('Image URL for the device.'),
   image_alt_text: z
     .string()
@@ -635,6 +640,7 @@ export const device = z
     ---
     route_path: /devices
     ---
+    Represents a [device](https://docs.seam.co/latest/core-concepts/devices) that has been connected to Seam.
   `)
 
 export type Device = z.infer<typeof device>

package/src/lib/seam/connect/models/devices/unmanaged-device.ts

@@ -38,6 +38,7 @@ export const unmanaged_device = device
     ---
     route_path: /devices/unmanaged
     ---
+    Represents an [unmanaged device](https://docs.seam.co/latest/core-concepts/devices/managed-and-unmanaged-devices). An unmanaged device has a limited set of visible properties and a subset of supported events. You cannot control an unmanaged device. Any [access codes](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes/migrating-existing-access-codes) on an unmanaged device are unmanaged. To control an unmanaged device with Seam, [convert it to a managed device](https://docs.seam.co/latest/core-concepts/devices/managed-and-unmanaged-devices#convert-an-unmanaged-device-to-managed).
   `)
 
 export type UnmanagedDevice = z.infer<typeof unmanaged_device>

package/src/lib/seam/connect/models/events/seam-event.ts

@@ -28,6 +28,9 @@ export const seam_event = z.discriminatedUnion('event_type', [
   ---
   route_path: /events
   ---
+  Represents an event. Events let you know when something interesting happens in your workspace. For example, when a lock is unlocked, Seam creates a \`lock.unlocked\` event. When a device's battery level is low, Seam creates a \`device.battery_low\` event.
+  
+  As with other API resources, you can retrieve an individual event or a list of events. Seam also provides a separate [webhook](https://docs.seam.co/latest/developer-tools/webhooks) system for sending the event objects directly to an endpoint on your sever. Manage webhooks through [Seam Console](https://console.seam.co). You can also use the webhooks sandbox in Seam Console to see the different payloads for each event and test them against your own endpoints.
 `)
 
 export type SeamEvent = z.infer<typeof seam_event>

package/src/lib/seam/connect/models/user-identities/user-identity.ts

@@ -35,7 +35,7 @@ export const user_identity = z.object({
   ---
   route_path: /user_identities
   ---
-  Represents a [user identity](https://docs.seam.co/latest/capability-guides/mobile-access-in-development/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) associated with an application user account.
+  Represents a [user identity](https://docs.seam.co/latest/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) associated with an application user account.
 `)
 
 export type UserIdentity = z.output<typeof user_identity>

package/src/lib/seam/connect/models/workspaces/workspace.ts

@@ -32,6 +32,7 @@ export const workspace = z.object({
   ---
   route_path: /workspaces
   ---
+  Represents a Seam [workspace](https://docs.seam.co/latest/core-concepts/workspaces). A workspace is a top-level entity that encompasses all other resources below it, such as devices, connected accounts, and Connect Webviews. Seam provides two types of workspaces. A [sandbox workspace](https://docs.seam.co/latest/core-concepts/workspaces#sandbox-workspaces) is a special type of workspace designed for testing code. Sandbox workspaces offer test device accounts and virtual devices that you can connect and control. This ability to work with virtual devices is quite handy because it removes the need to own physical devices from multiple brands. To connect real devices and systems to Seam, use a [production workspace](https://docs.seam.co/latest/core-concepts/workspaces#production-workspaces).
 `)
 
 export type Workspace = z.infer<typeof workspace>