@seamapi/types 1.405.0 → 1.406.1

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

@@ -40,7 +40,8 @@ export const LOCK_DEVICE_TYPE_LIST = Object.values(
 
 export const lock_device_type = z.enum(
   Object.values(LOCK_DEVICE_TYPE) as [LockDeviceTypeFromMapping],
-)
+).describe(`Device type for smartlocks.
+          `)
 
 export type LockDeviceType = z.infer<typeof lock_device_type>
 
@@ -59,7 +60,8 @@ export const NOISE_SENSOR_DEVICE_TYPE_LIST = Object.values(
 
 export const noise_sensor_device_type = z.enum(
   Object.values(NOISE_SENSOR_DEVICE_TYPE) as [NoiseSensorDeviceTypeFromMapping],
-)
+).describe(`Device type for noise sensors.
+          `)
 
 export type NoiseSensorDeviceType = z.infer<typeof noise_sensor_device_type>
 
@@ -82,7 +84,8 @@ export const THERMOSTAT_DEVICE_TYPE_LIST = Object.values(
 
 export const thermostat_device_type = z.enum(
   Object.values(THERMOSTAT_DEVICE_TYPE) as [ThermostatDeviceTypeFromMapping],
-)
+).describe(`Device type for thermostats.
+          `)
 
 export type ThermostatDeviceType = z.infer<typeof thermostat_device_type>
 
@@ -99,9 +102,10 @@ export const PHONE_DEVICE_TYPE_LIST = Object.values(
   PHONE_DEVICE_TYPE,
 ) as PhoneDeviceTypeFromMapping[]
 
-export const phone_device_type = z
-  .enum(Object.values(PHONE_DEVICE_TYPE_LIST) as [PhoneDeviceTypeFromMapping])
-  .describe('Type of phone.')
+export const phone_device_type = z.enum(
+  Object.values(PHONE_DEVICE_TYPE_LIST) as [PhoneDeviceTypeFromMapping],
+).describe(`Device type for phones.
+          `)
 
 export type PhoneDeviceType = z.infer<typeof phone_device_type>
 

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

@@ -18,6 +18,8 @@ export const device_capability_flags =
   })
 
 export const battery_status = z.enum(['critical', 'low', 'good', 'full'])
+  .describe(`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.
+          `)
 
 export type BatteryStatus = z.infer<typeof battery_status>
 
@@ -404,108 +406,136 @@ export const common_device_properties = z.object({
       `),
   accessory_keypad: z
     .object({
-      is_connected: z
-        .boolean()
-        .describe(
-          'Indicates if the accessory_keypad is connected to the device.',
-        ),
+      is_connected: z.boolean()
+        .describe(`Indicates if an accessory keypad is connected to the device.
+        `),
       battery: z
         .object({
           level: z.number().min(0).max(1),
         })
-        .optional()
-        .describe('Indicates if the keypad battery properties.'),
+        .optional().describe(`Keypad battery properties.
+          `),
     })
-    .optional()
-    .describe('Represents the accessory keypad state.'),
+    .optional().describe(`
+          ---
+          property_group_key: hardware
+          ---
+          Accessory keypad properties and state.
+          `),
   appearance: z.object({
     name: z
       .string()
       .describe(
         'Name of the device as seen from the provider API and application, not settable through Seam.',
       ),
-  }),
-  model: z.object({
-    can_connect_accessory_keypad: z
-      .boolean()
-      .optional()
-      .describe('Indicates whether the device can connect a accessory keypad.'),
-    display_name: z.string().describe('Display name of the device model.'),
-    manufacturer_display_name: z
-      .string()
-      .describe(
-        'Display name that corresponds to the manufacturer-specific terminology for the device.',
-      ),
-    has_built_in_keypad: z
-      .boolean()
-      .optional()
-      .describe(
-        'Indicates whether the device has a built in accessory keypad.',
-      ),
-    offline_access_codes_supported: z
-      .boolean()
-      .optional()
-      .describe('Indicates whether the device supports offline access codes.'),
-    online_access_codes_supported: z
-      .boolean()
-      .optional()
-      .describe('Indicates whether the device supports online access codes.'),
-    accessory_keypad_supported: z
-      .boolean()
-      .optional()
-      .describe(
-        `
-      ---
-      deprecated: use device.properties.model.can_connect_accessory_keypad
-      ---
-      `,
-      ),
-  }),
-  has_direct_power: z
-    .boolean()
-    .optional()
-    .describe('Indicates whether the device has direct power.'),
-  battery_level: z
-    .number()
-    .min(0)
-    .max(1)
-    .optional()
-    .describe(
-      'Indicates the battery level of the device as a decimal value between 0 and 1, inclusive.',
-    ),
+  }).describe(`
+          ---
+          property_group_key: hardware
+          ---
+          Appearance-related properties, as reported by the device.
+          `),
+  model: z
+    .object({
+      can_connect_accessory_keypad: z.boolean().optional().describe(`
+          Indicates whether the device can connect a accessory keypad.
+      `),
+      display_name: z.string().describe(`
+          Display name of the device model.
+      `),
+      manufacturer_display_name: z.string().describe(`
+          Display name that corresponds to the manufacturer-specific terminology for the device.
+      `),
+      has_built_in_keypad: z.boolean().optional().describe(`
+          Indicates whether the device has a built in accessory keypad.
+      `),
+      offline_access_codes_supported: z.boolean().optional().describe(`
+          ---
+          deprecated: use device.can_program_offline_access_codes.
+          ---
+          `),
+      online_access_codes_supported: z.boolean().optional().describe(`
+          ---
+          deprecated: use device.can_program_online_access_codes.
+          ---
+          `),
+      accessory_keypad_supported: z.boolean().optional().describe(`
+        ---
+        deprecated: use device.properties.model.can_connect_accessory_keypad
+        ---
+        `),
+    })
+    .describe(`Device model-related properties.`),
+  has_direct_power: z.boolean().optional().describe(`
+          ---
+          property_group_key: hardware
+          ---
+          Indicates whether the device has direct power.
+          `),
+  battery_level: z.number().min(0).max(1).optional().describe(`
+          ---
+          property_group_key: hardware
+          ---
+          Indicates the battery level of the device as a decimal value between 0 and 1, inclusive.
+          `),
   battery: z
     .object({
-      level: z.number().min(0).max(1),
+      level: z.number().min(0).max(1)
+        .describe(`Battery charge level as a value between 0 and 1, inclusive.
+          `),
       status: battery_status,
     })
-    .optional()
-    .describe(
-      '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.',
-    ),
+    .optional().describe(`
+          ---
+          property_group_key: hardware
+          ---
+          Represents the current status of the battery charge level.
+          `),
   // todo: use enum
-  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()
-    .optional()
-    .describe('Alt text for the device image.'),
-  serial_number: z.string().optional().describe('Serial number of the device.'),
+  manufacturer: z.string().optional().describe(`
+          ---
+          property_group_key: hardware
+          ---
+          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(`
+          ---
+          property_group_key: hardware
+          ---
+          Image URL for the device.
+          `),
+  image_alt_text: z.string().optional().describe(`
+          ---
+          property_group_key: hardware
+          ---
+          Alt text for the device image.
+          `),
+  serial_number: z.string().optional().describe(`
+          ---
+          property_group_key: hardware
+          ---
+          Serial number of the device.
+          `),
 
   online_access_codes_enabled: z
     .boolean()
     .describe(
-      'Indicates whether it is currently possible to use online access codes for the device.',
+      `
+          ---
+          property_group_key: access_codes
+          ---
+          Indicates whether it is currently possible to use online access codes for the device.
+          `,
     )
     .optional(),
   offline_access_codes_enabled: z
     .boolean()
     .describe(
-      'Indicates whether it is currently possible to use offline access codes for the device.',
+      `
+          ---
+          property_group_key: access_codes
+          ---
+          Indicates whether it is currently possible to use offline access codes for the device.
+          `,
     )
     .optional(),
 
@@ -516,6 +546,7 @@ export const common_device_properties = z.object({
       `
       ---
       deprecated: use device.properties.model.can_connect_accessory_keypad
+      property_group_key: access_codes
       ---
       `,
     )
@@ -526,6 +557,7 @@ export const common_device_properties = z.object({
       `
       ---
       deprecated: use offline_access_codes_enabled
+      property_group_key: access_codes
       ---
       `,
     )
@@ -533,12 +565,24 @@ export const common_device_properties = z.object({
   noise_level_decibels: z
     .number()
     .describe(
-      'Indicates current noise level in decibels, if the device supports noise detection.',
+      `
+          ---
+          property_group_key: noise_sensors
+          ---
+          Indicates current noise level in decibels, if the device supports noise detection.
+          `,
     )
     .optional(),
   currently_triggering_noise_threshold_ids: z
     .array(z.string())
-    .describe('Array of noise threshold IDs that are currently triggering.')
+    .describe(
+      `
+          ---
+          property_group_key: noise_sensors
+          ---
+          Array of noise threshold IDs that are currently triggering.
+          `,
+    )
     .optional(),
 })
 
@@ -569,30 +613,48 @@ export const device = z
       .describe(
         'Display name of the device, defaults to nickname (if it is set) or properties.appearance.name otherwise. Enables administrators and users to identify the device easily, especially when there are numerous devices.',
       ),
-    capabilities_supported: z
-      .array(capabilities)
-      .describe(
-        'Collection of capabilities that the device supports when connected to Seam. Values are "access_code," which indicates that the device can manage and utilize digital PIN codes for secure access; "lock," which indicates that the device controls a door locking mechanism, enabling the remote opening and closing of doors and other entry points; "noise_detection," which indicates that the device supports monitoring and responding to ambient noise levels; "thermostat," which indicates that the device can regulate and adjust indoor temperatures; and "battery," which indicates that the device can manage battery life and health.',
-      ),
+    capabilities_supported: z.array(capabilities).describe(`
+        Collection of capabilities that the device supports when connected to Seam. Values are \`access_code\`, which indicates that the device can manage and utilize digital PIN codes for secure access; \`lock\`, which indicates that the device controls a door locking mechanism, enabling the remote opening and closing of doors and other entry points; \`noise_detection\`, which indicates that the device supports monitoring and responding to ambient noise levels; \`thermostat\`, which indicates that the device can regulate and adjust indoor temperatures; \`battery\`, which indicates that the device can manage battery life and health; and \`phone\`, which indicates that the device is a mobile device, such as a smartphone. **Important:** Superseded by [capability flags](https://docs.seam.co/latest/capability-guides/device-and-system-capabilities#capability-flags).
+        `),
     properties: common_device_properties
       .and(phone_specific_properties.partial())
       .and(device_metadata)
-      .and(capability_properties)
-      .describe('Properties of the device.'),
+      .and(capability_properties).describe(`
+    ---
+    property_groups:
+      locks:
+        name: Locks
+      access_codes:
+        name: Access Codes
+      thermostats:
+        name: Thermostats
+      hardware:
+        name: Hardware
+      noise_sensors:
+        name: Noise Sensors
+      phones:
+        name: Phones
+      provider_metadata:
+        name: Provider Metadata
+    ---
+    Properties of the device.
+  `),
     location: z
       // todo: optional instead of nullable
       .object({
-        location_name: z
-          .string()
-          .optional()
-          .describe('Name of the device location.'),
-        timezone: z
-          .string()
-          .optional()
-          .describe('Time zone of the device location.'),
+        location_name: z.string().optional()
+          .describe(`Name of the device location.
+          `),
+        timezone: z.string().optional()
+          .describe(`Time zone of the device location.
+          `),
       })
-      .nullable()
-      .describe('Location information for the device.'),
+      .nullable().describe(`
+          ---
+          property_group_key: hardware
+          ---
+          Location information for the device.
+          `),
     connected_account_id: z
       .string()
       .uuid()
@@ -639,6 +701,21 @@ export const device = z
   .merge(device_capability_flags).describe(`
     ---
     route_path: /devices
+    property_groups:
+      locks:
+        name: Locks
+      access_codes:
+        name: Access Codes
+      thermostats:
+        name: Thermostats
+      hardware:
+        name: Hardware
+      noise_sensors:
+        name: Noise Sensors
+      phones:
+        name: Phones
+      provider_metadata:
+        name: Provider Metadata
     ---
     Represents a [device](https://docs.seam.co/latest/core-concepts/devices) that has been connected to Seam.
   `)

package/src/lib/seam/connect/models/devices/phone-properties.ts

@@ -1,39 +1,37 @@
 import { z } from 'zod'
 
-export const phone_specific_properties = z
-  .object({
-    assa_abloy_credential_service_metadata: z
-      .object({
-        has_active_endpoint: z
-          .boolean()
-          .describe(
-            'Indicates whether the credential service has active endpoints associated with the phone.',
-          ),
-        endpoints: z
-          .array(
-            z.object({
-              endpoint_id: z
-                .string()
-                .describe('ID of the associated endpoint.'),
-              is_active: z
-                .boolean()
-                .describe('Indicated whether the endpoint is active.'),
-            }),
-          )
-          .describe('Endpoints associated with the phone.'),
-      })
-      .optional()
-      .describe('ASSA ABLOY Credential Service metadata for the phone.'),
+export const phone_specific_properties = z.object({
+  assa_abloy_credential_service_metadata: z
+    .object({
+      has_active_endpoint: z
+        .boolean()
+        .describe(
+          'Indicates whether the credential service has active endpoints associated with the phone.',
+        ),
+      endpoints: z
+        .array(
+          z.object({
+            endpoint_id: z.string().describe('ID of the associated endpoint.'),
+            is_active: z
+              .boolean()
+              .describe('Indicated whether the endpoint is active.'),
+          }),
+        )
+        .describe('Endpoints associated with the phone.'),
+    })
+    .optional()
+    .describe('ASSA ABLOY Credential Service metadata for the phone.'),
 
-    salto_space_credential_service_metadata: z
-      .object({
-        has_active_phone: z
-          .boolean()
-          .describe(
-            'Indicates whether the credential service has an active associated phone.',
-          ),
-      })
-      .optional()
-      .describe('Salto Space credential service metadata for the phone.'),
-  })
-  .describe('Properties of the phone.')
+  salto_space_credential_service_metadata: z
+    .object({
+      has_active_phone: z
+        .boolean()
+        .describe(
+          'Indicates whether the credential service has an active associated phone.',
+        ),
+    })
+    .optional()
+    .describe('Salto Space credential service metadata for the phone.'),
+}).describe(`
+          Properties of the phone.
+          `)

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

@@ -16,23 +16,23 @@ const basePhoneDeviceSchema = device.pick({
 })
 
 export const phone = z.object({
-  device_id:
-    basePhoneDeviceSchema.shape.device_id.describe('ID of the `phone`.'),
-  nickname: basePhoneDeviceSchema.shape.nickname.describe(
-    'Optional nickname to describe the phone, settable through Seam.',
-  ),
-  display_name: basePhoneDeviceSchema.shape.display_name.describe(
-    'Display name of the phone. Defaults to `nickname` (if it is set) or `properties.appearance.name` otherwise. Enables administrators and users to identify the phone easily, especially when there are numerous phones.',
-  ),
-  workspace_id: basePhoneDeviceSchema.shape.workspace_id.describe(
-    'ID of the [workspace](https://docs.seam.co/latest/core-concepts/workspaces) that contains the `phone`.',
-  ),
-  created_at: basePhoneDeviceSchema.shape.created_at.describe(
-    'Date and time at which the `phone` was created.',
-  ),
-  custom_metadata: basePhoneDeviceSchema.shape.custom_metadata.describe(
-    'Optional [custom metadata](https://docs.seam.co/latest/core-concepts/devices/adding-custom-metadata-to-a-device) for the phone.',
-  ),
+  device_id: basePhoneDeviceSchema.shape.device_id.describe(`ID of the phone.
+          `),
+  nickname: basePhoneDeviceSchema.shape.nickname
+    .describe(`Optional nickname to describe the phone, settable through Seam.
+  `),
+  display_name: basePhoneDeviceSchema.shape.display_name
+    .describe(`Display name of the phone. Defaults to \`nickname\` (if it is set) or \`properties.appearance.name\` otherwise. Enables administrators and users to identify the phone easily, especially when there are numerous phones.
+  `),
+  workspace_id: basePhoneDeviceSchema.shape.workspace_id
+    .describe(`ID of the [workspace](https://docs.seam.co/latest/core-concepts/workspaces) that contains the phone.
+  `),
+  created_at: basePhoneDeviceSchema.shape.created_at
+    .describe(`Date and time at which the phone was created.
+  `),
+  custom_metadata: basePhoneDeviceSchema.shape.custom_metadata
+    .describe(`Optional [custom metadata](https://docs.seam.co/latest/core-concepts/devices/adding-custom-metadata-to-a-device) for the phone.
+  `),
 
   errors: z
     .array(
@@ -41,7 +41,7 @@ export const phone = z.object({
         message: z.string(),
       }),
     )
-    .describe('Errors associated with the `phone`.'),
+    .describe('Errors associated with the phone.'),
   warnings: z
     .array(
       z.object({
@@ -49,12 +49,15 @@ export const phone = z.object({
         message: z.string(),
       }),
     )
-    .describe('Warnings associated with the `phone`.'),
+    .describe('Warnings associated with the phone.'),
   device_type: phone_device_type,
   properties: phone_specific_properties,
 }).describe(`
   ---
   route_path: /phones
+  property_groups:
+    phones:
+      name: Phones
   ---
   Represents an app user's mobile phone.
 `)

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

@@ -32,11 +32,45 @@ export const unmanaged_device = device
       online_access_codes_enabled: true,
       offline_access_codes_enabled: true,
       model: true,
-    }),
+    }).describe(`
+    ---
+    property_groups:
+      locks:
+        name: locks
+      access_codes:
+        name: access codes
+      thermostats:
+        name: thermostats
+      hardware:
+        name: hardware
+      noise_sensors:
+        name: noise sensors
+      phones:
+        name: phones
+      provider_metadata:
+        name: provider metadata
+    ---
+    properties of the device.
+  `),
   })
   .merge(device_capability_flags).describe(`
     ---
     route_path: /devices/unmanaged
+    property_groups:
+      locks:
+        name: Locks
+      access_codes:
+        name: Access Codes
+      thermostats:
+        name: Thermostats
+      hardware:
+        name: Hardware
+      noise_sensors:
+        name: Noise Sensors
+      phones:
+        name: Phones
+      provider_metadata:
+        name: Provider Metadata
     ---
     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).
   `)

package/src/lib/seam/connect/models/index.ts

@@ -14,6 +14,7 @@ export * from './instant-keys/index.js'
 export * from './locations/index.js'
 export * from './noise-sensors/index.js'
 export * from './pagination.js'
+export * from './partner/index.js'
 export * from './phone-number.js'
 export * from './phones/index.js'
 export * from './thermostats/index.js'

package/src/lib/seam/connect/models/partner/index.ts

@@ -0,0 +1 @@
+export * from './resources.js'

package/src/lib/seam/connect/models/partner/resources.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+
+export const partner_resource = z.object({
+  partner_resource_type: z.string(),
+  partner_resource_key: z.string(),
+  customer_key: z.string(),
+
+  // For user identity partner resources
+  email_address: z.string().optional(),
+  phone_number: z.string().optional(),
+
+  // For access grant partner resources
+  starts_at: z.string().optional(),
+  ends_at: z.string().optional(),
+  user_identity_key: z.string().optional(),
+  location_keys: z.array(z.string()).optional(),
+
+  // Common
+  name: z.string().optional(),
+  description: z.string().optional(),
+  custom_metadata: z.record(z.string(), z.string()).optional(),
+})
+
+export type PartnerResource = z.infer<typeof partner_resource>