@seamapi/types 1.312.2 → 1.313.0

package/package.json

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

package/src/lib/seam/connect/models/events/common.ts

@@ -1,28 +1,16 @@
 import { z } from 'zod'
 
 export const common_event = z.object({
-  event_id: z.string().uuid().describe(`
-    ---
-    title: Event ID
-    ---
-    The ID of the event.
-  `),
-  workspace_id: z.string().uuid().describe(`
-    ---
-    title: Workspace ID
-    ---
-    The ID of the workspace.
-  `),
-  created_at: z.string().datetime().describe(`
-    ---
-    title: Created At
-    ---
-    The time when the event was created.
-  `),
-  occurred_at: z.string().datetime().describe(`
-    ---
-    title: Occurred At
-    ---
-    The time when the event occurred.
-  `),
+  event_id: z.string().uuid().describe('ID of the event.'),
+  workspace_id: z
+    .string()
+    .uuid()
+    .describe(
+      'ID of the [workspace](https://docs.seam.co/latest/core-concepts/workspaces).',
+    ),
+  created_at: z
+    .string()
+    .datetime()
+    .describe('Time at which the event was created.'),
+  occurred_at: z.string().datetime().describe('Time when the event occurred.'),
 })

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

@@ -4,58 +4,38 @@ import { climate_setting } from '../thermostats/climate-preset.js'
 import { common_event } from './common.js'
 
 const device_event = common_event.extend({
-  device_id: z.string().uuid().describe(`
-    ---
-    title: Device ID
-    ---
-    ID of the device.
-  `),
-  connected_account_id: z.string().uuid().describe(`
-    ---
-    title: Connected Account ID
-    ---
-    ID of the connected account.
-  `),
+  device_id: z.string().uuid().describe('ID of the device.'),
+  connected_account_id: z
+    .string()
+    .uuid()
+    .describe(
+      'ID of the [connected account](https://docs.seam.co/latest/core-concepts/connected-accounts).',
+    ),
 })
 
-const battery_level = z.number().min(0).max(1).describe(`
-  ---
-  title: Battery Level
-  ---
-  Fractional number 0 to 1.0 indicating amount of battery in device, as reported by device.
-`)
-
-const device_battery_status = z.enum(['critical', 'low', 'good', 'full'])
-  .describe(`
-  ---
-  title: Battery Status
-  ---
-  Enum representing the battery status calculated from numeric battery_level value, one of 'critical' | 'low' | 'good' | 'full'
-`)
-
-const disconnection_error_code = z.enum([
-  'account_disconnected',
-  'hub_disconnected',
-  'device_disconnected',
-]).describe(`
-  ---
-  title: Event Error Code
-  ---
-  The error code associated with the event, if any.
-`)
-
-export const lock_method = z.enum([
-  'keycode',
-  'manual',
-  'automatic',
-  'unknown',
-  'seamapi',
-]).describe(`
-  ---
-  title: Lock Lock/Unlock Method
-  ---
-  Method by which a lock device was locked or unlocked. When the method is \`keycode\`, the \`access_code_id\` will reference the Seam access code which was used, if reported by the device.
-`)
+const battery_level = z
+  .number()
+  .min(0)
+  .max(1)
+  .describe(
+    'Number in the range 0 to 1.0 indicating the amount of battery in the device, as reported by the device.',
+  )
+
+const device_battery_status = z
+  .enum(['critical', 'low', 'good', 'full'])
+  .describe(
+    'Battery status of the device, calculated from the numeric `battery_level` value.',
+  )
+
+const disconnection_error_code = z
+  .enum(['account_disconnected', 'hub_disconnected', 'device_disconnected'])
+  .describe('Error code associated with the disconnection event, if any.')
+
+export const lock_method = z
+  .enum(['keycode', 'manual', 'automatic', 'unknown', 'seamapi'])
+  .describe(
+    'Method by which a lock device was locked or unlocked. When the method is `keycode`, the `access_code_id` indicates the [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) that was used, if reported by the device.',
+  )
 export type LockMethod = z.infer<typeof lock_method>
 
 export const device_connected_event = device_event
@@ -70,7 +50,7 @@ export const device_added_event = device_event
   .extend({
     event_type: z.literal('device.added'),
   })
-  .describe('A device has been added or reconnected to Seam.')
+  .describe('A device was added or reconnected to Seam.')
 
 export type DeviceAddedEvent = z.infer<typeof device_added_event>
 
@@ -79,7 +59,7 @@ export const device_converted_to_unmanaged_event = device_event
     event_type: z.literal('device.converted_to_unmanaged'),
   })
   .describe(
-    'An unmanaged device was successfully converted to a managed device.',
+    'An [unmanaged device](https://docs.seam.co/latest/core-concepts/devices/managed-and-unmanaged-devices) was successfully converted to a managed device.',
   )
 
 export type DeviceConvertedToUnmanagedEvent = z.infer<
@@ -91,7 +71,7 @@ export const unmanaged_device_converted_to_managed_event = device_event
     event_type: z.literal('device.unmanaged.converted_to_managed'),
   })
   .describe(
-    'A managed device was successfully converted to an unmanaged device.',
+    'A managed device was successfully converted to an [unmanaged device](https://docs.seam.co/latest/core-concepts/devices/managed-and-unmanaged-devices).',
   )
 
 export type UnmanagedDeviceConvertedToManagedEvent = z.infer<
@@ -102,7 +82,9 @@ export const unmanaged_device_connected_event = device_event
   .extend({
     event_type: z.literal('device.unmanaged.connected'),
   })
-  .describe('An unmanaged device was connected to Seam')
+  .describe(
+    'An [unmanaged device](https://docs.seam.co/latest/core-concepts/devices/managed-and-unmanaged-devices) was connected to Seam.',
+  )
 
 export type UnmanagedDeviceConnectedEvent = z.infer<
   typeof unmanaged_device_connected_event
@@ -113,7 +95,7 @@ export const device_disconnected_event = device_event
     event_type: z.literal('device.disconnected'),
     error_code: disconnection_error_code,
   })
-  .describe('A device was disconnected')
+  .describe('A device was disconnected from Seam.')
 
 export type DeviceDisconnectedEvent = z.infer<typeof device_disconnected_event>
 
@@ -122,7 +104,9 @@ export const unmanaged_device_disconnected_event = device_event
     event_type: z.literal('device.unmanaged.disconnected'),
     error_code: disconnection_error_code,
   })
-  .describe('An unmanaged device was disconnected')
+  .describe(
+    'An [unmanaged device](https://docs.seam.co/latest/core-concepts/devices/managed-and-unmanaged-devices) was disconnected from Seam.',
+  )
 
 export type UnmanagedDeviceDisconnectedEvent = z.infer<
   typeof unmanaged_device_disconnected_event
@@ -133,7 +117,7 @@ export const device_tampered_event = device_event
     event_type: z.literal('device.tampered'),
   })
   .describe(
-    'A device detected that it was tampered with, e.g., opened or moved.',
+    'A device detected that it was tampered with, for example, opened or moved.',
   )
 
 export type DeviceTamperedEvent = z.infer<typeof device_tampered_event>
@@ -154,7 +138,7 @@ export const device_battery_status_changed_event = device_event
     battery_level,
   })
   .describe(
-    'A device battery status changed since the last battery status changed event.',
+    'A device battery status changed since the last `battery_status_changed` event.',
   )
 
 export type DeviceBatteryStatusChangedEvent = z.infer<
@@ -165,7 +149,9 @@ export const device_removed_event = device_event
   .extend({
     event_type: z.literal('device.removed'),
   })
-  .describe('A device was removed externally from the connected account.')
+  .describe(
+    'A device was removed externally from the [connected account](https://docs.seam.co/latest/core-concepts/connected-accounts).',
+  )
 
 export type DeviceRemovedEvent = z.infer<typeof device_removed_event>
 
@@ -173,7 +159,9 @@ export const device_deleted_event = device_event
   .extend({
     event_type: z.literal('device.deleted'),
   })
-  .describe('A device was deleted.')
+  .describe(
+    'A device was [deleted](https://docs.seam.co/latest/api/devices/delete).',
+  )
 
 export type DeviceDeletedEvent = z.infer<typeof device_deleted_event>
 
@@ -182,7 +170,7 @@ export const device_third_party_integration_detected_event = device_event
     event_type: z.literal('device.third_party_integration_detected'),
   })
   .describe(
-    'Seam detected a device is using a third party integration that will interfere with Seam device management.',
+    'Seam detected that a device is using a third-party integration that will interfere with Seam device management.',
   )
 
 export type DeviceThirdPartyIntegrationDetectedEvent = z.infer<
@@ -197,7 +185,7 @@ export const device_third_party_integration_no_longer_detected_event =
       ),
     })
     .describe(
-      'Seam detected a device is no longer using a third party integration that was interfering with Seam device management.',
+      'Seam detected that a device is no longer using a third-party integration that was interfering with Seam device management.',
     )
 
 export type DeviceThirdPartyIntegrationNoLongerDetectedEvent = z.infer<
@@ -238,7 +226,9 @@ export const device_connection_stabilized_event = device_event
   .extend({
     event_type: z.literal('device.connection_stabilized'),
   })
-  .describe('Seam detected a previously flaky device connection stabilized.')
+  .describe(
+    'Seam detected that a previously-flaky device connection stabilized.',
+  )
 
 export type DeviceConnectionStabilizedEvent = z.infer<
   typeof device_connection_stabilized_event
@@ -249,7 +239,7 @@ export const device_error_subscription_required_event = device_event
     event_type: z.literal('device.error.subscription_required'),
   })
   .describe(
-    'A third party subscription is required to use all device features.',
+    'A third-party subscription is required to use all device features.',
   )
 
 export type DeviceErrorSubscriptionRequiredEvent = z.infer<
@@ -261,7 +251,7 @@ export const device_error_subscription_required_resolved_event = device_event
     event_type: z.literal('device.error.subscription_required.resolved'),
   })
   .describe(
-    'A third party subscription is active or no longer-required to use all device features.',
+    'A third-party subscription is active or no longer required to use all device features.',
   )
 
 export type DeviceErrorSubscriptionRequiredResolvedEvent = z.infer<
@@ -272,7 +262,7 @@ export const device_accessory_keypad_connected_event = device_event
   .extend({
     event_type: z.literal('device.accessory_keypad_connected'),
   })
-  .describe('A accessory keypad was connected to a device.')
+  .describe('An accessory keypad was connected to a device.')
 
 export type DeviceAccessoryKeypadConnectedEvent = z.infer<
   typeof device_accessory_keypad_connected_event
@@ -282,7 +272,7 @@ export const device_accessory_keypad_disconnected_event = device_event
   .extend({
     event_type: z.literal('device.accessory_keypad_disconnected'),
   })
-  .describe('A accessory keypad was disconnected to a device.')
+  .describe('An accessory keypad was disconnected from a device.')
 
 export type DeviceAccessoryKeypadDisconnectedEvent = z.infer<
   typeof device_accessory_keypad_disconnected_event
@@ -291,26 +281,43 @@ export type DeviceAccessoryKeypadDisconnectedEvent = z.infer<
 export const noise_sensor_noise_threshold_triggered_event = device_event
   .extend({
     event_type: z.literal('noise_sensor.noise_threshold_triggered'),
-    noise_level_decibels: z.number().optional(),
-    noise_level_nrs: z.number().optional(),
-    noise_threshold_id: z.string().uuid().optional(),
-    noise_threshold_name: z.string().optional(),
+    noise_level_decibels: z
+      .number()
+      .optional()
+      .describe('Detected noise level in decibels.'),
+    noise_level_nrs: z
+      .number()
+      .optional()
+      .describe('Detected noise level in Noiseaware Noise Risk Score (NRS).'),
+    noise_threshold_id: z
+      .string()
+      .uuid()
+      .optional()
+      .describe(
+        'ID of the [noise threshold](https://docs.seam.co/latest/capability-guides/noise-sensors#what-is-a-threshold) that was triggered.',
+      ),
+    noise_threshold_name: z
+      .string()
+      .optional()
+      .describe(
+        'Name of the [noise threshold](https://docs.seam.co/latest/capability-guides/noise-sensors#what-is-a-threshold) that was triggered.',
+      ),
     // TODO: remove metadata from this event
     noiseaware_metadata: z.record(z.unknown()).optional().describe(`
       ---
       title: Noiseaware Metadata
       ---
-      Metadata from the Noiseaware API.
+      Metadata from Noiseaware.
     `),
     minut_metadata: z.record(z.unknown()).optional().describe(`
       ---
       title: Minut Metadata
       ---
-      Metadata from the Minut API.
+      Metadata from Minut.
     `),
   })
   .describe(
-    'Extended periods of noise or noise exceeding a threshold was detected.',
+    'Extended periods of noise or noise exceeding a [threshold](https://docs.seam.co/latest/capability-guides/noise-sensors#what-is-a-threshold) were detected.',
   )
 
 export type NoiseSensorNoiseThresholdTriggeredEvent = z.infer<
@@ -320,9 +327,23 @@ export type NoiseSensorNoiseThresholdTriggeredEvent = z.infer<
 export const lock_locked_event = device_event
   .extend({
     event_type: z.literal('lock.locked'),
-    access_code_id: z.string().uuid().optional(),
-    action_attempt_id: z.string().uuid().optional(),
-    method: lock_method,
+    access_code_id: z
+      .string()
+      .uuid()
+      .optional()
+      .describe(
+        'ID of the [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) that was used to lock the device.',
+      ),
+    action_attempt_id: z
+      .string()
+      .uuid()
+      .optional()
+      .describe(
+        'ID of the [action attempt](https://docs.seam.co/latest/core-concepts/action-attempts) associated with the lock action.',
+      ),
+    method: lock_method.describe(
+      'Method by which a lock device was locked. When the method is `keycode`, the `access_code_id` indicates the [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) that was used, if reported by the device.',
+    ),
   })
   .describe('A lock was locked.')
 
@@ -331,9 +352,23 @@ export type LockLockedEvent = z.infer<typeof lock_locked_event>
 export const lock_unlocked_event = device_event
   .extend({
     event_type: z.literal('lock.unlocked'),
-    access_code_id: z.string().uuid().optional(),
-    action_attempt_id: z.string().uuid().optional(),
-    method: lock_method,
+    access_code_id: z
+      .string()
+      .uuid()
+      .optional()
+      .describe(
+        'ID of the [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) that was used to unlock the device.',
+      ),
+    action_attempt_id: z
+      .string()
+      .uuid()
+      .optional()
+      .describe(
+        'ID of the [action attempt](https://docs.seam.co/latest/core-concepts/action-attempts) associated with the unlock action.',
+      ),
+    method: lock_method.describe(
+      'Method by which a lock device was unlocked. When the method is `keycode`, the `access_code_id` indicates the [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) that was used, if reported by the device.',
+    ),
   })
   .describe('A lock was unlocked.')
 
@@ -342,7 +377,13 @@ export type LockUnlockedEvent = z.infer<typeof lock_unlocked_event>
 export const lock_access_denied_event = device_event
   .extend({
     event_type: z.literal('lock.access_denied'),
-    access_code_id: z.string().uuid().optional(),
+    access_code_id: z
+      .string()
+      .uuid()
+      .optional()
+      .describe(
+        'ID of the [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) that was used in the unlock attempts.',
+      ),
   })
   .describe(
     'The lock denied access to a user after one or more consecutive invalid attempts to unlock the device.',
@@ -353,17 +394,37 @@ export type LockAccessDeniedEvent = z.infer<typeof lock_access_denied_event>
 export const thermostat_climate_preset_activated_event = device_event
   .extend({
     event_type: z.literal('thermostat.climate_preset_activated'),
-    thermostat_schedule_id: z.string().uuid().nullable(),
-    climate_preset_key: z.string(),
-    is_fallback_climate_preset: z.boolean(),
+    thermostat_schedule_id: z
+      .string()
+      .uuid()
+      .nullable()
+      .describe(
+        'ID of the [thermostat schedule](https://docs.seam.co/latest/capability-guides/thermostats/creating-and-managing-thermostat-schedules) that prompted the [climate preset](https://docs.seam.co/latest/capability-guides/thermostats/creating-and-managing-climate-presets) to be activated.',
+      ),
+    climate_preset_key: z
+      .string()
+      .describe(
+        'Key of the [climate preset](https://docs.seam.co/latest/capability-guides/thermostats/creating-and-managing-climate-presets) that was activated.',
+      ),
+    is_fallback_climate_preset: z
+      .boolean()
+      .describe(
+        'Indicates whether the [climate preset](https://docs.seam.co/latest/capability-guides/thermostats/creating-and-managing-climate-presets) that was activated is the [fallback climate preset](https://docs.seam.co/latest/capability-guides/thermostats/creating-and-managing-climate-presets/setting-the-fallback-climate-preset) for the thermostat.',
+      ),
   })
-  .describe('A thermostat climate preset was activated.')
+  .describe(
+    'A thermostat [climate preset](https://docs.seam.co/latest/capability-guides/thermostats/creating-and-managing-climate-presets) was activated.',
+  )
 
 export type ThermostatClimatePresetActivatedEvent = z.infer<
   typeof thermostat_climate_preset_activated_event
 >
 
-export const thermostat_manually_adjusted_method = z.enum(['seam', 'external'])
+export const thermostat_manually_adjusted_method = z
+  .enum(['seam', 'external'])
+  .describe(
+    'Method used to adjust the thermostat manually. `seam` indicates that the Seam API, Seam CLI, or Seam Console was used to adjust the thermostat.',
+  )
 
 export const thermostat_manually_adjusted_event = device_event
   .extend({
@@ -380,7 +441,7 @@ export const thermostat_manually_adjusted_event = device_event
       heating_set_point_fahrenheit: true,
     }),
   )
-  .describe('A thermostat was manually adjusted.')
+  .describe('A thermostat was adjusted manually.')
 
 export type ThermostatManuallyAdjustedEvent = z.infer<
   typeof thermostat_manually_adjusted_event
@@ -389,14 +450,40 @@ export type ThermostatManuallyAdjustedEvent = z.infer<
 export const temperature_threshold_exceeded_event = device_event
   .extend({
     event_type: z.literal('thermostat.temperature_threshold_exceeded'),
-    temperature_celsius: z.number(),
-    temperature_fahrenheit: z.number(),
-    upper_limit_celsius: z.number().nullable(),
-    upper_limit_fahrenheit: z.number().nullable(),
-    lower_limit_celsius: z.number().nullable(),
-    lower_limit_fahrenheit: z.number().nullable(),
+    temperature_celsius: z
+      .number()
+      .describe('Temperature, in °C, reported by the thermostat.'),
+    temperature_fahrenheit: z
+      .number()
+      .describe('Temperature, in °F, reported by the thermostat.'),
+    upper_limit_celsius: z
+      .number()
+      .nullable()
+      .describe(
+        'Upper temperature limit, in °C, defined by the set [threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).',
+      ),
+    upper_limit_fahrenheit: z
+      .number()
+      .nullable()
+      .describe(
+        'Upper temperature limit, in °F, defined by the set [threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).',
+      ),
+    lower_limit_celsius: z
+      .number()
+      .nullable()
+      .describe(
+        'Lower temperature limit, in °C, defined by the set [threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).',
+      ),
+    lower_limit_fahrenheit: z
+      .number()
+      .nullable()
+      .describe(
+        'Lower temperature limit, in °F, defined by the set [threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).',
+      ),
   })
-  .describe("A thermostat's temperature reading exceeded the set threshold.")
+  .describe(
+    "A thermostat's temperature reading exceeded the set [threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).",
+  )
 
 export type TemperatureThresholdExceededEvent = z.infer<
   typeof temperature_threshold_exceeded_event
@@ -407,15 +494,39 @@ export const temperature_threshold_no_longer_exceeded_event = device_event
     event_type: z.literal(
       'thermostat.temperature_threshold_no_longer_exceeded',
     ),
-    temperature_celsius: z.number(),
-    temperature_fahrenheit: z.number(),
-    upper_limit_celsius: z.number().nullable(),
-    upper_limit_fahrenheit: z.number().nullable(),
-    lower_limit_celsius: z.number().nullable(),
-    lower_limit_fahrenheit: z.number().nullable(),
+    temperature_celsius: z
+      .number()
+      .describe('Temperature, in °C, reported by the thermostat.'),
+    temperature_fahrenheit: z
+      .number()
+      .describe('Temperature, in °F, reported by the thermostat.'),
+    upper_limit_celsius: z
+      .number()
+      .nullable()
+      .describe(
+        'Upper temperature limit, in °C, defined by the set [threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).',
+      ),
+    upper_limit_fahrenheit: z
+      .number()
+      .nullable()
+      .describe(
+        'Upper temperature limit, in °F, defined by the set [threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).',
+      ),
+    lower_limit_celsius: z
+      .number()
+      .nullable()
+      .describe(
+        'Lower temperature limit, in °C, defined by the set [threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).',
+      ),
+    lower_limit_fahrenheit: z
+      .number()
+      .nullable()
+      .describe(
+        'Lower temperature limit, in °F, defined by the set [threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).',
+      ),
   })
   .describe(
-    "A thermostat's temperature reading is no longer exceeding the set threshold.",
+    "A thermostat's temperature reading no longer exceeds the set [threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds).",
   )
 
 export type TemperatureThresholdNoLongerExceededEvent = z.infer<