@seamapi/http 2.0.0 → 2.2.0

package/src/lib/seam/connect/routes/access-grants/access-grants.ts

@@ -168,6 +168,9 @@ export class SeamHttpAccessGrants {
     return SeamHttpAccessGrantsUnmanaged.fromClient(this.client, this.defaults)
   }
 
+  /**
+   * Creates a new [Access Grant](https://docs.seam.co/use-cases/granting-access/access-grants). Access Grants are the default and recommended way to grant a user access to any physical space, irrespective of the locking hardware. They work with both standalone smart locks (using `device_ids`) and access control systems (using `acs_entrance_ids` or `space_ids`), and can issue PIN codes, key cards, and mobile keys through a single request.
+   */
   create(
     parameters: AccessGrantsCreateParameters,
     options: AccessGrantsCreateOptions = {},
@@ -181,6 +184,9 @@ export class SeamHttpAccessGrants {
     })
   }
 
+  /**
+   * Delete an Access Grant.
+   */
   delete(
     parameters: AccessGrantsDeleteParameters,
     options: AccessGrantsDeleteOptions = {},
@@ -194,6 +200,9 @@ export class SeamHttpAccessGrants {
     })
   }
 
+  /**
+   * Get an Access Grant.
+   */
   get(
     parameters?: AccessGrantsGetParameters,
     options: AccessGrantsGetOptions = {},
@@ -207,6 +216,9 @@ export class SeamHttpAccessGrants {
     })
   }
 
+  /**
+   * Gets all related resources for one or more Access Grants.
+   */
   getRelated(
     parameters?: AccessGrantsGetRelatedParameters,
     options: AccessGrantsGetRelatedOptions = {},
@@ -220,6 +232,9 @@ export class SeamHttpAccessGrants {
     })
   }
 
+  /**
+   * Gets an Access Grant.
+   */
   list(
     parameters?: AccessGrantsListParameters,
     options: AccessGrantsListOptions = {},
@@ -233,6 +248,9 @@ export class SeamHttpAccessGrants {
     })
   }
 
+  /**
+   * Adds additional requested access methods to an existing Access Grant.
+   */
   requestAccessMethods(
     parameters: AccessGrantsRequestAccessMethodsParameters,
     options: AccessGrantsRequestAccessMethodsOptions = {},
@@ -246,6 +264,9 @@ export class SeamHttpAccessGrants {
     })
   }
 
+  /**
+   * Updates an existing Access Grant's time window.
+   */
   update(
     parameters?: AccessGrantsUpdateParameters,
     options: AccessGrantsUpdateOptions = {},
@@ -261,38 +282,111 @@ export class SeamHttpAccessGrants {
 }
 
 export type AccessGrantsCreateParameters = {
+  /**
+   * ID of user identity for whom access is being granted.
+   */
   user_identity_id?: string | undefined
+  /**
+   * When used, creates a new user identity with the given details, and grants them access.
+   */
   user_identity?:
     | {
+        /**
+         * Unique email address for the user identity.
+         */
         email_address?: string | undefined
+        /**
+         * Full name of the user associated with the user identity.
+         */
         full_name?: string | undefined
+        /**
+         * Unique phone number for the user identity in [E.164 format](https://www.itu.int/rec/T-REC-E.164/en) (for example, +15555550100).
+         */
         phone_number?: string | undefined
+        /**
+         * Unique key for the user identity.
+         */
         user_identity_key?: string | undefined
       }
     | undefined
+  /**
+   * Unique key for the access grant within the workspace.
+   */
   access_grant_key?: string | undefined
+  /**
+   * Set of IDs of the [entrances](https://docs.seam.co/api/acs/systems/list) to which access is being granted.
+   */
   acs_entrance_ids?: Array<string> | undefined
+  /**
+   * ID of the customization profile to apply to the Access Grant and its access methods.
+   */
   customization_profile_id?: string | undefined
+  /**
+   * Set of IDs of the [devices](https://docs.seam.co/api/devices/list) to which access is being granted.
+   */
   device_ids?: Array<string> | undefined
+  /**
+   * Date and time at which the validity of the new grant ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. Must be a time in the future and after `starts_at`.
+   */
   ends_at?: string | undefined
+  /**
+   * @deprecated Create a space first, then reference it using `space_ids`.
+   */
   location?:
     | {
+        /**
+         * @deprecated Use `acs_entrance_ids` at the top level.
+         */
         acs_entrance_ids?: Array<string> | undefined
+        /**
+         * @deprecated Use `device_ids` at the top level.
+         */
         device_ids?: Array<string> | undefined
+        /**
+         * Name of the location.
+         */
         name?: string | undefined
       }
     | undefined
+  /**
+   * @deprecated Use `space_ids`.
+   */
   location_ids?: Array<string> | undefined
+  /**
+   * Name for the access grant.
+   */
   name?: string | undefined
+
   requested_access_methods: Array<{
+    /**
+     * Specific PIN code to use for this access method. Only applicable when mode is 'code'.
+     */
     code?: string | undefined
+    /**
+     * Maximum number of times the instant key can be used. Only applicable when mode is 'mobile_key'. Defaults to 1 if not specified.
+     */
     instant_key_max_use_count?: number | undefined
+    /**
+     * Access method mode. Supported values: `code`, `card`, `mobile_key`, `cloud_key`.
+     */
     mode?: 'code' | 'card' | 'mobile_key' | 'cloud_key' | undefined
   }>
 
+  /**
+   * Reservation key for the access grant.
+   */
   reservation_key?: string | undefined
+  /**
+   * Set of IDs of existing spaces to which access is being granted.
+   */
   space_ids?: Array<string> | undefined
+  /**
+   * Set of keys of existing spaces to which access is being granted.
+   */
   space_keys?: Array<string> | undefined
+  /**
+   * Date and time at which the validity of the new grant starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
+   */
   starts_at?: string | undefined
 }
 
@@ -309,6 +403,9 @@ export type AccessGrantsCreateRequest = SeamHttpRequest<
 export interface AccessGrantsCreateOptions {}
 
 export type AccessGrantsDeleteParameters = {
+  /**
+   * ID of Access Grant to delete.
+   */
   access_grant_id: string
 }
 
@@ -322,7 +419,13 @@ export type AccessGrantsDeleteRequest = SeamHttpRequest<void, undefined>
 export interface AccessGrantsDeleteOptions {}
 
 export type AccessGrantsGetParameters = {
+  /**
+   * ID of Access Grant to get.
+   */
   access_grant_id?: string | undefined
+  /**
+   * Unique key of Access Grant to get.
+   */
   access_grant_key?: string | undefined
 }
 
@@ -339,8 +442,15 @@ export type AccessGrantsGetRequest = SeamHttpRequest<
 export interface AccessGrantsGetOptions {}
 
 export type AccessGrantsGetRelatedParameters = {
+  /**
+   * IDs of the access grants that you want to get along with their related resources.
+   */
   access_grant_ids?: Array<string> | undefined
+  /**
+   * Keys of the access grants that you want to get along with their related resources.
+   */
   access_grant_keys?: Array<string> | undefined
+
   exclude?:
     | Array<
         | 'spaces'
@@ -353,6 +463,7 @@ export type AccessGrantsGetRelatedParameters = {
         | 'access_methods'
       >
     | undefined
+
   include?:
     | Array<
         | 'spaces'
@@ -391,18 +502,57 @@ export type AccessGrantsGetRelatedRequest = SeamHttpRequest<
 export interface AccessGrantsGetRelatedOptions {}
 
 export type AccessGrantsListParameters = {
+  /**
+   * ID of the access code by which you want to filter the list of Access Grants.
+   */
   access_code_id?: string | undefined
+  /**
+   * IDs of the access grants to retrieve.
+   */
   access_grant_ids?: Array<string> | undefined
+  /**
+   * Filter Access Grants by access_grant_key. Use null to filter for Access Grants without an access_grant_key.
+   */
   access_grant_key?: string | undefined
+  /**
+   * ID of the entrance by which you want to filter the list of Access Grants.
+   */
   acs_entrance_id?: string | undefined
+  /**
+   * ID of the access system by which you want to filter the list of Access Grants.
+   */
   acs_system_id?: string | undefined
+  /**
+   * Customer key for which you want to list access grants.
+   */
   customer_key?: string | undefined
+  /**
+   * ID of the device by which you want to filter the list of Access Grants.
+   */
   device_id?: string | undefined
+  /**
+   * Numerical limit on the number of access grants to return.
+   */
   limit?: number | undefined
+  /**
+   * @deprecated Use `space_id`.
+   */
   location_id?: string | undefined
+  /**
+   * Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+   */
   page_cursor?: string | undefined
+  /**
+   * Filter Access Grants by reservation_key.
+   */
   reservation_key?: string | undefined
+  /**
+   * ID of the space by which you want to filter the list of Access Grants.
+   */
   space_id?: string | undefined
+  /**
+   * ID of user identity by which you want to filter the list of Access Grants.
+   */
   user_identity_id?: string | undefined
 }
 
@@ -419,11 +569,26 @@ export type AccessGrantsListRequest = SeamHttpRequest<
 export interface AccessGrantsListOptions {}
 
 export type AccessGrantsRequestAccessMethodsParameters = {
+  /**
+   * ID of the Access Grant to add access methods to.
+   */
   access_grant_id: string
 
+  /**
+   * Array of requested access methods to add to the access grant.
+   */
   requested_access_methods: Array<{
+    /**
+     * Specific PIN code to use for this access method. Only applicable when mode is 'code'.
+     */
     code?: string | undefined
+    /**
+     * Maximum number of times the instant key can be used. Only applicable when mode is 'mobile_key'. Defaults to 1 if not specified.
+     */
     instant_key_max_use_count?: number | undefined
+    /**
+     * Access method mode. Supported values: `code`, `card`, `mobile_key`, `cloud_key`.
+     */
     mode?: 'code' | 'card' | 'mobile_key' | 'cloud_key' | undefined
   }>
 }
@@ -443,10 +608,25 @@ export type AccessGrantsRequestAccessMethodsRequest = SeamHttpRequest<
 export interface AccessGrantsRequestAccessMethodsOptions {}
 
 export type AccessGrantsUpdateParameters = {
+  /**
+   * ID of the Access Grant to update. Provide either `access_grant_id` or `access_grant_key`.
+   */
   access_grant_id?: string | undefined
+  /**
+   * Key of the Access Grant to update. Provide either `access_grant_id` or `access_grant_key`.
+   */
   access_grant_key?: string | undefined
+  /**
+   * Date and time at which the validity of the grant ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. Must be a time in the future and after `starts_at`.
+   */
   ends_at?: string | undefined
+  /**
+   * Display name for the access grant.
+   */
   name?: string | undefined
+  /**
+   * Date and time at which the validity of the grant starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
+   */
   starts_at?: string | undefined
 }
 

package/src/lib/seam/connect/routes/access-grants/unmanaged/unmanaged.ts

@@ -161,6 +161,9 @@ export class SeamHttpAccessGrantsUnmanaged {
     await clientSessions.get()
   }
 
+  /**
+   * Get an unmanaged Access Grant (where is_managed = false).
+   */
   get(
     parameters: AccessGrantsUnmanagedGetParameters,
     options: AccessGrantsUnmanagedGetOptions = {},
@@ -174,6 +177,9 @@ export class SeamHttpAccessGrantsUnmanaged {
     })
   }
 
+  /**
+   * Gets unmanaged Access Grants (where is_managed = false).
+   */
   list(
     parameters?: AccessGrantsUnmanagedListParameters,
     options: AccessGrantsUnmanagedListOptions = {},
@@ -187,6 +193,13 @@ export class SeamHttpAccessGrantsUnmanaged {
     })
   }
 
+  /**
+   * Updates an unmanaged Access Grant to make it managed.
+   *
+   * This endpoint can only be used to convert unmanaged access grants to managed ones by setting `is_managed` to `true`. It cannot be used to convert managed access grants back to unmanaged.
+   *
+   * When converting an unmanaged access grant to managed, all associated access methods will also be converted to managed.
+   */
   update(
     parameters: AccessGrantsUnmanagedUpdateParameters,
     options: AccessGrantsUnmanagedUpdateOptions = {},
@@ -202,6 +215,9 @@ export class SeamHttpAccessGrantsUnmanaged {
 }
 
 export type AccessGrantsUnmanagedGetParameters = {
+  /**
+   * ID of unmanaged Access Grant to get.
+   */
   access_grant_id: string
 }
 
@@ -220,11 +236,29 @@ export type AccessGrantsUnmanagedGetRequest = SeamHttpRequest<
 export interface AccessGrantsUnmanagedGetOptions {}
 
 export type AccessGrantsUnmanagedListParameters = {
+  /**
+   * ID of the entrance by which you want to filter the list of unmanaged Access Grants.
+   */
   acs_entrance_id?: string | undefined
+  /**
+   * ID of the access system by which you want to filter the list of unmanaged Access Grants.
+   */
   acs_system_id?: string | undefined
+  /**
+   * Numerical limit on the number of unmanaged access grants to return.
+   */
   limit?: number | undefined
+  /**
+   * Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+   */
   page_cursor?: string | undefined
+  /**
+   * Filter unmanaged Access Grants by reservation_key.
+   */
   reservation_key?: string | undefined
+  /**
+   * ID of user identity by which you want to filter the list of unmanaged Access Grants.
+   */
   user_identity_id?: string | undefined
 }
 
@@ -243,9 +277,18 @@ export type AccessGrantsUnmanagedListRequest = SeamHttpRequest<
 export interface AccessGrantsUnmanagedListOptions {}
 
 export type AccessGrantsUnmanagedUpdateParameters = {
+  /**
+   * ID of the unmanaged Access Grant to update.
+   */
   access_grant_id: string
 
+  /**
+   * Unique key for the access grant. If not provided, the existing key will be preserved.
+   */
   access_grant_key?: string | undefined
+  /**
+   * Must be set to true to convert the unmanaged access grant to managed.
+   */
   is_managed: boolean
 }
 

package/src/lib/seam/connect/routes/access-methods/access-methods.ts

@@ -169,6 +169,9 @@ export class SeamHttpAccessMethods {
     return SeamHttpAccessMethodsUnmanaged.fromClient(this.client, this.defaults)
   }
 
+  /**
+   * Assigns a pre-registered card credential, identified by `card_number`, to a card-mode access method. Use this endpoint for access systems that use pre-registered cards, where a physical card must be associated with an access method before it can be used for access. Assigning a card credential also triggers issuance of the access method.
+   */
   assignCard(
     parameters: AccessMethodsAssignCardParameters,
     options: AccessMethodsAssignCardOptions = {},
@@ -182,6 +185,9 @@ export class SeamHttpAccessMethods {
     })
   }
 
+  /**
+   * Deletes an access method.
+   */
   delete(
     parameters?: AccessMethodsDeleteParameters,
     options: AccessMethodsDeleteOptions = {},
@@ -195,6 +201,9 @@ export class SeamHttpAccessMethods {
     })
   }
 
+  /**
+   * Encodes an existing access method onto a plastic card placed on the specified [encoder](https://docs.seam.co/low-level-apis/access-systems/working-with-card-encoders-and-scanners).
+   */
   encode(
     parameters: AccessMethodsEncodeParameters,
     options: AccessMethodsEncodeOptions = {},
@@ -208,6 +217,9 @@ export class SeamHttpAccessMethods {
     })
   }
 
+  /**
+   * Gets an access method.
+   */
   get(
     parameters: AccessMethodsGetParameters,
     options: AccessMethodsGetOptions = {},
@@ -221,6 +233,9 @@ export class SeamHttpAccessMethods {
     })
   }
 
+  /**
+   * Gets all related resources for one or more Access Methods.
+   */
   getRelated(
     parameters: AccessMethodsGetRelatedParameters,
     options: AccessMethodsGetRelatedOptions = {},
@@ -234,6 +249,9 @@ export class SeamHttpAccessMethods {
     })
   }
 
+  /**
+   * Lists all access methods, usually filtered by Access Grant.
+   */
   list(
     parameters?: AccessMethodsListParameters,
     options: AccessMethodsListOptions = {},
@@ -247,6 +265,9 @@ export class SeamHttpAccessMethods {
     })
   }
 
+  /**
+   * Remotely unlocks a specified [entrance](https://docs.seam.co/low-level-apis/access-systems/retrieving-entrance-details) using the cloud key credential associated with an access method. Returns an action attempt that tracks the progress of the unlock operation.
+   */
   unlockDoor(
     parameters: AccessMethodsUnlockDoorParameters,
     options: AccessMethodsUnlockDoorOptions = {},
@@ -262,8 +283,14 @@ export class SeamHttpAccessMethods {
 }
 
 export type AccessMethodsAssignCardParameters = {
+  /**
+   * ID of the `access_method` to assign the credential to.
+   */
   access_method_id: string
 
+  /**
+   * Card number of the credential to assign.
+   */
   card_number: string
 }
 
@@ -283,8 +310,17 @@ export type AccessMethodsAssignCardOptions = Pick<
 >
 
 export type AccessMethodsDeleteParameters = {
+  /**
+   * ID of access method to delete.
+   */
   access_method_id?: string | undefined
+  /**
+   * ID of access grant whose access methods should be deleted.
+   */
   access_grant_id?: string | undefined
+  /**
+   * Reservation key of the access grant whose access methods should be deleted.
+   */
   reservation_key?: string | undefined
 }
 
@@ -298,8 +334,14 @@ export type AccessMethodsDeleteRequest = SeamHttpRequest<void, undefined>
 export interface AccessMethodsDeleteOptions {}
 
 export type AccessMethodsEncodeParameters = {
+  /**
+   * ID of the `access_method` to encode onto a card.
+   */
   access_method_id: string
 
+  /**
+   * ID of the `acs_encoder` to use to encode the `access_method`.
+   */
   acs_encoder_id: string
 }
 
@@ -319,6 +361,9 @@ export type AccessMethodsEncodeOptions = Pick<
 >
 
 export type AccessMethodsGetParameters = {
+  /**
+   * ID of access method to get.
+   */
   access_method_id: string
 }
 
@@ -335,6 +380,9 @@ export type AccessMethodsGetRequest = SeamHttpRequest<
 export interface AccessMethodsGetOptions {}
 
 export type AccessMethodsGetRelatedParameters = {
+  /**
+   * IDs of the access methods that you want to get along with their related resources.
+   */
   access_method_ids: Array<string>
 
   exclude?:
@@ -349,6 +397,7 @@ export type AccessMethodsGetRelatedParameters = {
         | 'acs_credentials'
       >
     | undefined
+
   include?:
     | Array<
         | 'spaces'
@@ -387,13 +436,37 @@ export type AccessMethodsGetRelatedRequest = SeamHttpRequest<
 export interface AccessMethodsGetRelatedOptions {}
 
 export type AccessMethodsListParameters = {
+  /**
+   * ID of the access code by which to filter the returned access methods. Must be combined with `access_grant_id`, `access_grant_key`, or `acs_entrance_id`.
+   */
   access_code_id?: string | undefined
+  /**
+   * ID of Access Grant to list access methods for.
+   */
   access_grant_id?: string | undefined
+  /**
+   * Key of Access Grant to list access methods for.
+   */
   access_grant_key?: string | undefined
+  /**
+   * ID of the entrance for which you want to retrieve all access methods that grant access to it.
+   */
   acs_entrance_id?: string | undefined
+  /**
+   * ID of the device by which to filter the returned access methods. Must be combined with `access_grant_id`, `access_grant_key`, or `acs_entrance_id`.
+   */
   device_id?: string | undefined
+  /**
+   * Maximum number of records to return per page.
+   */
   limit?: number | undefined
+  /**
+   * Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`.
+   */
   page_cursor?: string | undefined
+  /**
+   * ID of the space by which to filter the returned access methods. Must be combined with `access_grant_id`, `access_grant_key`, or `acs_entrance_id`.
+   */
   space_id?: string | undefined
 }
 
@@ -410,8 +483,14 @@ export type AccessMethodsListRequest = SeamHttpRequest<
 export interface AccessMethodsListOptions {}
 
 export type AccessMethodsUnlockDoorParameters = {
+  /**
+   * ID of the cloud_key `access_method` to use for the unlock operation.
+   */
   access_method_id: string
 
+  /**
+   * ID of the entrance to unlock.
+   */
   acs_entrance_id: string
 }
 

package/src/lib/seam/connect/routes/access-methods/unmanaged/unmanaged.ts

@@ -161,6 +161,9 @@ export class SeamHttpAccessMethodsUnmanaged {
     await clientSessions.get()
   }
 
+  /**
+   * Gets an unmanaged access method (where is_managed = false).
+   */
   get(
     parameters: AccessMethodsUnmanagedGetParameters,
     options: AccessMethodsUnmanagedGetOptions = {},
@@ -174,6 +177,9 @@ export class SeamHttpAccessMethodsUnmanaged {
     })
   }
 
+  /**
+   * Lists all unmanaged access methods (where is_managed = false), usually filtered by Access Grant.
+   */
   list(
     parameters: AccessMethodsUnmanagedListParameters,
     options: AccessMethodsUnmanagedListOptions = {},
@@ -189,6 +195,9 @@ export class SeamHttpAccessMethodsUnmanaged {
 }
 
 export type AccessMethodsUnmanagedGetParameters = {
+  /**
+   * ID of unmanaged access method to get.
+   */
   access_method_id: string
 }
 
@@ -207,10 +216,22 @@ export type AccessMethodsUnmanagedGetRequest = SeamHttpRequest<
 export interface AccessMethodsUnmanagedGetOptions {}
 
 export type AccessMethodsUnmanagedListParameters = {
+  /**
+   * ID of Access Grant to list unmanaged access methods for.
+   */
   access_grant_id: string
 
+  /**
+   * ID of the entrance for which you want to retrieve all unmanaged access methods.
+   */
   acs_entrance_id?: string | undefined
+  /**
+   * ID of the device for which you want to retrieve all unmanaged access methods.
+   */
   device_id?: string | undefined
+  /**
+   * ID of the space for which you want to retrieve all unmanaged access methods.
+   */
   space_id?: string | undefined
 }