feat: Add event documentation (#1426)

Author: seambot

src/lib/seam/connect/models/events/access-codes.ts

@@ -3,46 +3,49 @@ import { z } from 'zod'
 import { common_event } from './common.js'
 
 const access_code_event = common_event.extend({
-  access_code_id: z.string().uuid().describe(`
-    ---
-    title: Access Code ID
-    ---
-    The ID of the access code.
-  `),
-  device_id: z.string().uuid().describe(`
-    ---
-    title: Device ID
-    ---
-    The ID of the device.
-  `),
-  connected_account_id: z.string().uuid().describe(`
-    ---
-    title: Connected Account ID
-    ---
-    The ID of the connected account.
-  `),
+  access_code_id: z
+    .string()
+    .uuid()
+    .describe(
+      'ID of the [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes).',
+    ),
+  device_id: z
+    .string()
+    .uuid()
+    .describe(
+      'ID of the [device](https://docs.seam.co/latest/core-concepts/devices).',
+    ),
+  connected_account_id: z
+    .string()
+    .uuid()
+    .describe(
+      'ID of the [connected account](https://docs.seam.co/latest/core-concepts/connected-accounts).',
+    ),
 })
 
-const code = z.string().describe(`
-  ---
-  title: Access Code
-  ---
-  The code of the access code.
-`)
+const code = z
+  .string()
+  .describe(
+    'Code for the [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes).',
+  )
 
 export const access_code_created_event = access_code_event
   .extend({
     event_type: z.literal('access_code.created'),
   })
-  .describe('An access code was created.')
+  .describe(
+    'An [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) was created.',
+  )
 
 export type AccessCodeCreatedEvent = z.infer<typeof access_code_created_event>
 
 export const access_code_changed_event = access_code_event
   .extend({
     event_type: z.literal('access_code.changed'),
   })
-  .describe('An access code was changed.')
+  .describe(
+    'An [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) was changed.',
+  )
 
 export type AccessCodeChangedEvent = z.infer<typeof access_code_changed_event>
 
@@ -51,7 +54,9 @@ export const access_code_scheduled_on_device_event = access_code_event
     event_type: z.literal('access_code.scheduled_on_device'),
     code,
   })
-  .describe('An access code was natively scheduled on a device.')
+  .describe(
+    'An [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) was [scheduled natively](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes#native-scheduling) on a device.',
+  )
 
 export type AccessCodeScheduledOnDeviceEvent = z.infer<
   typeof access_code_scheduled_on_device_event
@@ -62,7 +67,9 @@ export const access_code_set_on_device_event = access_code_event
     event_type: z.literal('access_code.set_on_device'),
     code,
   })
-  .describe('An access code was set on a device.')
+  .describe(
+    'An [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) was set on a device.',
+  )
 
 export type AccessCodeSetOnDeviceEvent = z.infer<
   typeof access_code_set_on_device_event
@@ -72,7 +79,9 @@ export const access_code_removed_from_device_event = access_code_event
   .extend({
     event_type: z.literal('access_code.removed_from_device'),
   })
-  .describe('An access code was removed from a device.')
+  .describe(
+    'An [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) was removed from a device.',
+  )
 
 export type AccessCodeRemovedFromDeviceEvent = z.infer<
   typeof access_code_removed_from_device_event
@@ -83,7 +92,7 @@ export const access_code_delay_in_setting_on_device_event = access_code_event
     event_type: z.literal('access_code.delay_in_setting_on_device'),
   })
   .describe(
-    'There was an unusually long delay in setting an access code on a device.',
+    'There was an unusually long delay in setting an [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) on a device.',
   )
 
 export type AccessCodeDelayInSettingOnDeviceEvent = z.infer<
@@ -94,7 +103,9 @@ export const access_code_failed_to_set_on_device_event = access_code_event
   .extend({
     event_type: z.literal('access_code.failed_to_set_on_device'),
   })
-  .describe('An access code failed to be set on a device.')
+  .describe(
+    'An [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) failed to be set on a device.',
+  )
 
 export type AccessCodeFailedToSetOnDeviceEvent = z.infer<
   typeof access_code_failed_to_set_on_device_event
@@ -105,7 +116,9 @@ export const access_code_deleted_event = access_code_event
     event_type: z.literal('access_code.deleted'),
     code: code.nullable(),
   })
-  .describe('An access code was deleted.')
+  .describe(
+    'An [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) was deleted.',
+  )
 
 export type AccessCodeDeletedEvent = z.infer<typeof access_code_deleted_event>
 
@@ -114,7 +127,7 @@ export const access_code_delay_in_removing_from_device_event = access_code_event
     event_type: z.literal('access_code.delay_in_removing_from_device'),
   })
   .describe(
-    'There was an unusually long delay in removing an access code from a device.',
+    'There was an unusually long delay in removing an [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) from a device.',
   )
 
 export type AccessCodeDelayInRemovingFromDeviceEvent = z.infer<
@@ -125,7 +138,9 @@ export const access_code_failed_to_remove_from_device_event = access_code_event
   .extend({
     event_type: z.literal('access_code.failed_to_remove_from_device'),
   })
-  .describe('An access code failed to be removed from a device.')
+  .describe(
+    'An [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) failed to be removed from a device.',
+  )
 
 export type AccessCodeFailedToRemoveFromDeviceEvent = z.infer<
   typeof access_code_failed_to_remove_from_device_event
@@ -135,7 +150,9 @@ export const access_code_modified_external_to_seam_event = access_code_event
   .extend({
     event_type: z.literal('access_code.modified_external_to_seam'),
   })
-  .describe('An access code was modified external to Seam.')
+  .describe(
+    'An [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) was modified outside of Seam.',
+  )
 
 export type AccessCodeModifiedExternalToSeamEvent = z.infer<
   typeof access_code_modified_external_to_seam_event
@@ -145,7 +162,9 @@ export const access_code_deleted_external_to_seam_event = access_code_event
   .extend({
     event_type: z.literal('access_code.deleted_external_to_seam'),
   })
-  .describe('An access code was deleted external to Seam.')
+  .describe(
+    'An [access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes) was deleted outside of Seam.',
+  )
 
 export type AccessCodeDeletedExternalToSeamEvent = z.infer<
   typeof access_code_deleted_external_to_seam_event
@@ -157,7 +176,7 @@ export const access_code_backup_access_code_pulled_event = access_code_event
     backup_access_code_id: z.string(),
   })
   .describe(
-    'A backup access code was pulled from the backup access code pool and set on a device.',
+    'A [backup access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes/backup-access-codes) was pulled from the backup access code pool and set on a device.',
   )
 
 export type AccessCodeBackupAccessCodePulledEvent = z.infer<
@@ -170,7 +189,7 @@ export const unmanaged_access_code_converted_to_managed_event =
       event_type: z.literal('access_code.unmanaged.converted_to_managed'),
     })
     .describe(
-      'An unmanaged access code was successfully converted to a managed access code.',
+      'An [unmanaged access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes/migrating-existing-access-codes) was converted successfully to a managed access code.',
     )
 
 export type UnmanagedAccessCodeConvertedToManagedEvent = z.infer<
@@ -185,7 +204,7 @@ export const unmanaged_access_code_failed_to_convert_to_managed_event =
       ),
     })
     .describe(
-      'An unmanaged access code failed to be converted to a managed access code.',
+      'An [unmanaged access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes/migrating-existing-access-codes) failed to be converted to a managed access code.',
     )
 
 export type UnmanagedAccessCodeFailedToConvertToManagedEvent = z.infer<
@@ -196,7 +215,9 @@ export const unmanaged_access_code_created_event = access_code_event
   .extend({
     event_type: z.literal('access_code.unmanaged.created'),
   })
-  .describe('An unmanaged access code was created on a device.')
+  .describe(
+    'An [unmanaged access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes/migrating-existing-access-codes) was created on a device.',
+  )
 
 export type UnmanagedAccessCodeCreatedEvent = z.infer<
   typeof unmanaged_access_code_created_event
@@ -206,7 +227,9 @@ export const unmanaged_access_code_removed_event = access_code_event
   .extend({
     event_type: z.literal('access_code.unmanaged.removed'),
   })
-  .describe('An unmanaged access code was removed from a device.')
+  .describe(
+    'An [unmanaged access code](https://docs.seam.co/latest/capability-guides/smart-locks/access-codes/migrating-existing-access-codes) was removed from a device.',
+  )
 
 export type UnmanagedAccessCodeRemovedEvent = z.infer<
   typeof unmanaged_access_code_removed_event

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

@@ -3,16 +3,17 @@ import { z } from 'zod'
 import { common_event } from '../common.js'
 
 export const common_acs_event = common_event.extend({
-  connected_account_id: z.string().uuid().optional().describe(`
-    ---
-    title: Connected Account ID
-    ---
-    ID of the connected account.
-  `),
-  acs_system_id: z.string().uuid().describe(`
-    ---
-    title: ACS System ID
-    ---
-    ID of the ACS system.
-  `),
+  connected_account_id: z
+    .string()
+    .uuid()
+    .optional()
+    .describe(
+      'ID of the [connected account](https://docs.seam.co/latest/core-concepts/connected-accounts).',
+    ),
+  acs_system_id: z
+    .string()
+    .uuid()
+    .describe(
+      'ID of the [ACS system](https://docs.seam.co/latest/capability-guides/access-systems).',
+    ),
 })

src/lib/seam/connect/models/events/acs/credentials.ts

@@ -10,7 +10,9 @@ export const acs_credential_deleted_event = acs_credential_event
   .extend({
     event_type: z.literal('acs_credential.deleted'),
   })
-  .describe('An ACS credential was deleted.')
+  .describe(
+    'An [ACS credential](https://docs.seam.co/latest/capability-guides/access-systems/managing-credentials) was deleted.',
+  )
 
 export type AcsCredentialDeletedEvent = z.infer<
   typeof acs_credential_deleted_event
@@ -20,7 +22,9 @@ export const acs_credential_issued = acs_credential_event
   .extend({
     event_type: z.literal('acs_credential.issued'),
   })
-  .describe('An ACS credential was issued.')
+  .describe(
+    'An [ACS credential](https://docs.seam.co/latest/capability-guides/access-systems/managing-credentials) was issued.',
+  )
 
 export const acs_credential_events = [
   acs_credential_deleted_event,

src/lib/seam/connect/models/events/acs/encoders.ts

@@ -3,22 +3,31 @@ import { z } from 'zod'
 import { common_acs_event } from './common.js'
 
 const acs_encoder_event = common_acs_event.extend({
-  acs_encoder_id: z.string().uuid().describe('ID of the ACS encoder.'),
+  acs_encoder_id: z
+    .string()
+    .uuid()
+    .describe(
+      'ID of the [ACS encoder](https://docs.seam.co/latest/capability-guides/access-systems/working-with-card-encoders-and-scanners).',
+    ),
 })
 
 export const acs_encoder_added_event = acs_encoder_event
   .extend({
     event_type: z.literal('acs_encoder.added'),
   })
-  .describe('An ACS encoder was added.')
+  .describe(
+    'An [ACS encoder](https://docs.seam.co/latest/capability-guides/access-systems/working-with-card-encoders-and-scanners) was added.',
+  )
 
 export type AcsEncoderAddedEvent = z.infer<typeof acs_encoder_added_event>
 
 export const acs_encoder_removed_event = acs_encoder_event
   .extend({
     event_type: z.literal('acs_encoder.removed'),
   })
-  .describe('An ACS encoder was removed.')
+  .describe(
+    'An [ACS encoder](https://docs.seam.co/latest/capability-guides/access-systems/working-with-card-encoders-and-scanners) was removed.',
+  )
 
 export type AcsEncoderRemovedEvent = z.infer<typeof acs_encoder_removed_event>
 

src/lib/seam/connect/models/events/acs/systems.ts

@@ -8,15 +8,19 @@ export const acs_system_connected_event = acs_system_event
   .extend({
     event_type: z.literal('acs_system.connected'),
   })
-  .describe('An ACS system was connected.')
+  .describe(
+    'An [ACS system](https://docs.seam.co/latest/capability-guides/access-systems) was connected.',
+  )
 
 export type AcsSystemConnectedEvent = z.infer<typeof acs_system_connected_event>
 
 export const acs_system_disconnected_event = acs_system_event
   .extend({
     event_type: z.literal('acs_system.disconnected'),
   })
-  .describe('An ACS system was disconnected.')
+  .describe(
+    'An [ACS system](https://docs.seam.co/latest/capability-guides/access-systems) was disconnected.',
+  )
 
 export type AcsSystemDisconnectedEvent = z.infer<
   typeof acs_system_disconnected_event
@@ -26,7 +30,9 @@ export const acs_system_added_event = acs_system_event
   .extend({
     event_type: z.literal('acs_system.added'),
   })
-  .describe('An ACS system was added.')
+  .describe(
+    'An [ACS system](https://docs.seam.co/latest/capability-guides/access-systems) was added.',
+  )
 
 export type AcsSystemAddedEvent = z.infer<typeof acs_system_added_event>
 

src/lib/seam/connect/models/events/acs/users.ts

@@ -2,15 +2,21 @@ import { z } from 'zod'
 
 import { common_acs_event } from './common.js'
 
-const acs_user_event = common_acs_event.extend({
-  acs_user_id: z.string().uuid(),
-})
+const acs_user_event = common_acs_event
+  .extend({
+    acs_user_id: z.string().uuid(),
+  })
+  .describe(
+    'ID of the [ACS user](https://docs.seam.co/latest/capability-guides/access-systems/user-management).',
+  )
 
 export const acs_user_deleted_event = acs_user_event
   .extend({
     event_type: z.literal('acs_user.deleted'),
   })
-  .describe('An ACS user was deleted.')
+  .describe(
+    'An [ACS user](https://docs.seam.co/latest/capability-guides/access-systems/user-management) was deleted.',
+  )
 
 export type AcsUserDeletedEvent = z.infer<typeof acs_user_deleted_event>