@seamapi/types 1.406.0 → 1.406.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamapi/types",
-  "version": "1.406.0",
+  "version": "1.406.1",
   "description": "TypeScript types for the Seam API.",
   "type": "module",
   "main": "index.js",
@@ -92,7 +92,7 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
-    "@seamapi/blueprint": "^0.43.2",
+    "@seamapi/blueprint": "^0.43.5",
     "@types/node": "^20.8.10",
     "concurrently": "^8.2.0",
     "del-cli": "^5.0.0",

package/src/lib/seam/connect/models/devices/capabilities-supported.ts

@@ -7,6 +7,8 @@ export const capabilities = z.enum([
   'thermostat',
   'battery',
   'phone',
-])
+]).describe(`
+        Collection of capabilities that the device supports when connected to Seam. **Important:** Superseded by [capability flags](https://docs.seam.co/latest/capability-guides/device-and-system-capabilities#capability-flags).
+        `)
 
 export type Capabilities = z.infer<typeof capabilities>

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

@@ -1,45 +1,75 @@
 import { z } from 'zod'
 
-export const access_code_code_constraint = z.object({
-  constraint_type: z.enum([
-    'no_zeros', // Nuki
-    'cannot_start_with_12', // Nuki
-    'no_triple_consecutive_ints', // Brivo
-    'cannot_specify_pin_code', // Dormakaba?
-    'pin_code_matches_existing_set', // Salto
-    'start_date_in_future', // Kwikset
-    'no_ascending_or_descending_sequence', // Tedee
-    'at_least_three_unique_digits', // Tedee
-    'cannot_contain_089', // TTLock
-    'cannot_contain_0789', // TTLock (for some cylinder devices only)
-  ]),
-})
+export const access_code_code_constraint = z
+  .object({
+    constraint_type: z
+      .enum([
+        'no_zeros', // Nuki
+        'cannot_start_with_12', // Nuki
+        'no_triple_consecutive_ints', // Brivo
+        'cannot_specify_pin_code', // Dormakaba?
+        'pin_code_matches_existing_set', // Salto
+        'start_date_in_future', // Kwikset
+        'no_ascending_or_descending_sequence', // Tedee
+        'at_least_three_unique_digits', // Tedee
+        'cannot_contain_089', // TTLock
+        'cannot_contain_0789', // TTLock (for some cylinder devices only)
+      ])
+      .describe(`Code constraint type for access codes.`),
+  })
+  .describe(`Code constraint for access codes.`)
 
-export const access_code_name_constraint = z.object({
-  constraint_type: z.enum(['name_length', 'name_must_be_unique']), // Nuki, Kwikset
-  min_length: z.number().optional(),
-  max_length: z.number().optional(),
-})
+export const access_code_name_constraint = z
+  .object({
+    constraint_type: z.enum(['name_length', 'name_must_be_unique']), // Nuki, Kwikset
+    min_length: z
+      .number()
+      .optional()
+      .describe(`Minimum name length constraint for access codes.`),
+    max_length: z
+      .number()
+      .optional()
+      .describe(`Maximum name length constraint for access codes.`),
+  })
+  .describe(`Name constraint for access codes.`)
 
-export const access_code_constraint = z.union([
-  access_code_code_constraint,
-  access_code_name_constraint,
-])
+export const access_code_constraint = z
+  .union([access_code_code_constraint, access_code_name_constraint])
+  .describe(`Access code constraint.`)
 
 export type AccessCodeConstraint = z.infer<typeof access_code_constraint>
 
 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()
-    .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(),
-  has_native_entry_events: z.boolean().optional(),
+    .optional().describe(`
+          ---
+          undocumented: Marked as experimental.
+          ---
+          `),
+  code_constraints: z.array(access_code_constraint).optional().describe(`
+          ---
+          property_group_key: access_codes
+          ---
+          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().describe(`
+          ---
+          property_group_key: access_codes
+          ---
+          Supported code lengths for access codes.`),
+  max_active_codes_supported: z.number().optional().describe(`
+          ---
+          property_group_key: access_codes
+          ---
+          Maximum number of active access codes that the device supports.`),
+  supports_backup_access_code_pool: z.boolean().optional().describe(`
+          ---
+          property_group_key: access_codes
+          ---
+          Indicates whether the device supports a [backup access code pool](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes/backup-access-codes).`),
+  has_native_entry_events: z.boolean().optional().describe(`
+          ---
+          property_group_key: access_codes
+          ---
+          Indicates whether the device supports native entry events.`),
 })

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

@@ -1,11 +1,27 @@
 import { z } from 'zod'
 
 export const lock_capability_properties = z.object({
-  locked: z.boolean().optional(),
+  locked: z.boolean().optional().describe(`
+          ---
+          property_group_key: locks
+          ---
+          Indicates whether the lock is locked.
+          `),
   keypad_battery: z
     .object({
-      level: z.number(),
+      level: z.number().describe(`Keypad battery charge level.
+          `),
     })
-    .optional(),
-  door_open: z.boolean().optional(),
+    .optional().describe(`
+          ---
+          property_group_key: access_codes
+          ---
+          Keypad battery status.
+          `),
+  door_open: z.boolean().optional().describe(`
+          ---
+          property_group_key: locks
+          ---
+          Indicates whether the door is open.
+          `),
 })

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

@@ -12,56 +12,200 @@ import {
 
 export const thermostat_capability_properties = z
   .object({
-    temperature_fahrenheit: z.number(),
-    temperature_celsius: z.number(),
-    relative_humidity: z.number().min(0).max(1),
-    available_hvac_mode_settings: z.array(hvac_mode_setting),
-    available_fan_mode_settings: z.array(fan_mode_setting),
-    is_heating: z.boolean(),
-    is_cooling: z.boolean(),
-    is_fan_running: z.boolean(),
+    temperature_fahrenheit: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Reported temperature in °F.
+          `),
+    temperature_celsius: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Reported temperature in °C.
+          `),
+    relative_humidity: z.number().min(0).max(1).describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Reported relative humidity, as a value between 0 and 1, inclusive.
+          `),
+    available_hvac_mode_settings: z.array(hvac_mode_setting).describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          HVAC mode settings that the thermostat supports.
+          `),
+    available_fan_mode_settings: z.array(fan_mode_setting).describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Fan mode settings that the thermostat supports.
+          `),
+    is_heating: z.boolean().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Indicates whether the connected HVAC system is currently heating, as reported by the thermostat.
+          `),
+    is_cooling: z.boolean().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Indicates whether the connected HVAC system is currently cooling, as reported by the thermostat.
+          `),
+    is_fan_running: z.boolean().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Indicates whether the fan in the connected HVAC system is currently running, as reported by the thermostat.
+          `),
     fan_mode_setting: fan_mode_setting.describe(`
       ---
-      deprecated: use current_climate_setting.fan_mode_setting instead.
+      deprecated: Use \`current_climate_setting.fan_mode_setting\` instead.
+      property_group_key: thermostats
       ---
     `),
 
     /**
      * this is true if the current thermostat settings differ that what is on seam, and `current_climate_setting.manual_override_allowed: true`
      */
-    is_temporary_manual_override_active: z.boolean(),
+    is_temporary_manual_override_active: z.boolean().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Indicates whether the current thermostat settings differ from the most recent active program or schedule that Seam activated. For this condition to occur, \`current_climate_setting.manual_override_allowed\` must also be \`true\`.
+          `),
 
     /**
      * can be derived from `fallback_climate_preset_key`, or `active_thermostat_schedule` if one is active
      */
-    current_climate_setting: climate_setting,
+    current_climate_setting: climate_setting.describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Current climate setting.
+          `),
     default_climate_setting: climate_setting.describe(`
       ---
       deprecated: use fallback_climate_preset_key to specify a fallback climate preset instead.
+      property_group_key: thermostats
       ---
     `),
-    available_climate_presets: z.array(climate_preset),
-    fallback_climate_preset_key: z.string().min(1).nullable().default(null),
-    active_thermostat_schedule: thermostat_schedule.nullable().default(null),
-    thermostat_daily_programs: z.array(thermostat_daily_program).optional(),
-    thermostat_weekly_program: thermostat_weekly_program.nullable().optional(),
-    min_cooling_set_point_celsius: z.number(),
-    min_cooling_set_point_fahrenheit: z.number(),
-    max_cooling_set_point_celsius: z.number(),
-    max_cooling_set_point_fahrenheit: z.number(),
-    min_heating_set_point_celsius: z.number(),
-    min_heating_set_point_fahrenheit: z.number(),
-    max_heating_set_point_celsius: z.number(),
-    max_heating_set_point_fahrenheit: z.number(),
-    min_heating_cooling_delta_celsius: z.number(),
-    min_heating_cooling_delta_fahrenheit: z.number(),
+    available_climate_presets: z.array(climate_preset).describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Available [climate presets](https://docs.seam.co/latest/capability-guides/thermostats/creating-and-managing-climate-presets) for the thermostat.
+          `),
+    fallback_climate_preset_key: z.string().min(1).nullable().default(null)
+      .describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Key of 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.
+          `),
+    active_thermostat_schedule: thermostat_schedule.nullable().default(null)
+      .describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Active [thermostat schedule](https://docs.seam.co/latest/capability-guides/thermostats/creating-and-managing-thermostat-schedules).
+          `),
+    thermostat_daily_programs: z.array(thermostat_daily_program).optional()
+      .describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Configured [daily programs](https://docs.seam.co/latest/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.
+          `),
+    thermostat_weekly_program: thermostat_weekly_program.nullable().optional()
+      .describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Current [weekly program](https://docs.seam.co/latest/capability-guides/thermostats/creating-and-managing-thermostat-programs) for the thermostat.
+          `),
+    min_cooling_set_point_celsius: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Minimum [cooling set point](https://docs.seam.co/latest/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
+          `),
+    min_cooling_set_point_fahrenheit: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Minimum [cooling set point](https://docs.seam.co/latest/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
+          `),
+    max_cooling_set_point_celsius: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Maximum [cooling set point](https://docs.seam.co/latest/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °C.
+          `),
+    max_cooling_set_point_fahrenheit: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Maximum [cooling set point](https://docs.seam.co/latest/capability-guides/thermostats/understanding-thermostat-concepts/set-points#cooling-set-point) in °F.
+          `),
+    min_heating_set_point_celsius: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Minimum [heating set point](https://docs.seam.co/latest/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
+          `),
+    min_heating_set_point_fahrenheit: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Minimum [heating set point](https://docs.seam.co/latest/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
+          `),
+    max_heating_set_point_celsius: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Maximum [heating set point](https://docs.seam.co/latest/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °C.
+          `),
+    max_heating_set_point_fahrenheit: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Maximum [heating set point](https://docs.seam.co/latest/capability-guides/thermostats/understanding-thermostat-concepts/set-points#heating-set-point) in °F.
+          `),
+    min_heating_cooling_delta_celsius: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Minimum [temperature difference](https://docs.seam.co/latest/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °C between the cooling and heating set points when in heat-cool (auto) mode.
+          `),
+    min_heating_cooling_delta_fahrenheit: z.number().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Minimum [temperature difference](https://docs.seam.co/latest/capability-guides/thermostats/understanding-thermostat-concepts/set-points#minimum-heating-cooling-temperature-delta) in °F between the cooling and heating set points when in heat-cool (auto) mode.
+          `),
     temperature_threshold: z
       .object({
-        lower_limit_celsius: z.number().nullable(),
-        lower_limit_fahrenheit: z.number().nullable(),
-        upper_limit_celsius: z.number().nullable(),
-        upper_limit_fahrenheit: z.number().nullable(),
+        lower_limit_celsius: z.number().nullable()
+          .describe(`Lower limit in °C within the current [temperature threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
+          `),
+        lower_limit_fahrenheit: z.number().nullable()
+          .describe(`Lower limit in °F within the current [temperature threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
+          `),
+        upper_limit_celsius: z.number().nullable()
+          .describe(`Upper limit in °C within the current [temperature threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
+          `),
+        upper_limit_fahrenheit: z.number().nullable()
+          .describe(`Upper limit in °F within the current [temperature threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
+          `),
       })
-      .optional(),
+      .optional().describe(`
+          ---
+          property_group_key: thermostats
+          ---
+          Current [temperature threshold](https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds) set for the thermostat.
+          `),
   })
   .partial()