@seamapi/http 2.1.0 → 2.2.0

package/lib/seam/connect/resources/access-grant.d.ts

@@ -1,98 +1,367 @@
+/**
+ * Represents an Access Grant. Access Grants enable you to grant a user identity access to spaces, entrances, and devices through one or more access methods, such as mobile keys, plastic cards, and PIN codes. You can create an Access Grant for an existing user identity, or you can create a new user identity *while* creating the new Access Grant.
+ */
 export type AccessGrant = {
+    /**
+     * ID of the Access Grant.
+     */
     access_grant_id: string;
+    /**
+     * Unique key for the access grant within the workspace.
+     */
     access_grant_key?: string | undefined;
+    /**
+     * IDs of the access methods created for the Access Grant.
+     */
     access_method_ids: Array<string>;
+    /**
+     * Client Session Token. Only returned if the Access Grant has a mobile_key access method.
+     */
     client_session_token?: string | undefined;
+    /**
+     * Date and time at which the Access Grant was created.
+     */
     created_at: string;
+    /**
+     * ID of the customization profile associated with the Access Grant.
+     */
     customization_profile_id?: string | undefined;
+    /**
+     * Display name of the Access Grant.
+     */
     display_name: string;
+    /**
+     * Date and time at which the Access Grant ends.
+     */
     ends_at: string | null;
-    errors: Array<{
+    /**
+     * Errors associated with the [access grant](https://docs.seam.co/use-cases/granting-access).
+     */
+    errors: Array<
+    /**
+     * Indicates that Seam could not create one or more of the requested access methods for the access grant.
+     */
+    {
+        /**
+         * Date and time at which Seam created the error.
+         */
         created_at: string;
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
         error_code: 'cannot_create_requested_access_methods';
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * IDs of the devices that did not receive an access code at grant creation. Use these to identify which specific devices failed when the message reports a partial failure.
+         */
         missing_device_ids?: Array<string> | undefined;
     }>;
+    /**
+     * Instant Key URL. Only returned if the Access Grant has a single mobile_key access_method.
+     */
     instant_key_url?: string | undefined;
+    /**
+     * @deprecated Use `space_ids`.
+     */
     location_ids: Array<string>;
+    /**
+     * Name of the Access Grant. If not provided, the display name will be computed.
+     */
     name: string | null;
-    pending_mutations: Array<{
+    /**
+     * List of pending mutations for the access grant. This shows updates that are in progress.
+     */
+    pending_mutations: Array<
+    /**
+     * Seam is in the process of updating the devices/spaces associated with this access grant.
+     */
+    {
+        /**
+         * Date and time at which the mutation was created.
+         */
         created_at: string;
+        /**
+         * Previous location configuration.
+         */
         from: {
+            /**
+             * Previous device IDs where access codes existed.
+             */
             device_ids: Array<string>;
         };
+        /**
+         * Detailed description of the mutation.
+         */
         message: string;
+        /**
+         * Mutation code to indicate that Seam is in the process of updating the spaces (devices) associated with this access grant.
+         */
         mutation_code: 'updating_spaces';
+        /**
+         * New location configuration.
+         */
         to: {
+            /**
+             * Common code key to ensure PIN code reuse across devices.
+             */
             common_code_key?: string | null | undefined;
+            /**
+             * New device IDs where access codes should be created.
+             */
             device_ids: Array<string>;
         };
-    } | {
+    } /**
+   * Seam is in the process of updating the access times for this access grant.
+   */ | {
+        /**
+         * IDs of the access methods being updated.
+         */
         access_method_ids: Array<string>;
+        /**
+         * Date and time at which the mutation was created.
+         */
         created_at: string;
+        /**
+         * Previous access time configuration.
+         */
         from: {
+            /**
+             * Previous end time for access.
+             */
             ends_at: string | null;
+            /**
+             * Previous start time for access.
+             */
             starts_at: string | null;
         };
+        /**
+         * Detailed description of the mutation.
+         */
         message: string;
+        /**
+         * Mutation code to indicate that Seam is in the process of updating the access times for this access grant.
+         */
         mutation_code: 'updating_access_times';
+        /**
+         * New access time configuration.
+         */
         to: {
+            /**
+             * New end time for access.
+             */
             ends_at: string | null;
+            /**
+             * New start time for access.
+             */
             starts_at: string | null;
         };
     }>;
+    /**
+     * Access methods that the user requested for 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;
+        /**
+         * IDs of the access methods created for the requested access method.
+         */
         created_access_method_ids: Array<string>;
+        /**
+         * Date and time at which the requested access method was added to the Access Grant.
+         */
         created_at: string;
+        /**
+         * Display name of the access method.
+         */
         display_name: string;
+        /**
+         * 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';
     }>;
+    /**
+     * Reservation key for the access grant.
+     */
     reservation_key?: string | undefined;
+    /**
+     * IDs of the spaces to which the Access Grant gives access.
+     */
     space_ids: Array<string>;
+    /**
+     * Date and time at which the Access Grant starts.
+     */
     starts_at: string;
+    /**
+     * ID of user identity to which the Access Grant gives access.
+     */
     user_identity_id: string;
-    warnings: Array<{
+    /**
+     * Warnings associated with the [access grant](https://docs.seam.co/use-cases/granting-access).
+     */
+    warnings: Array<
+    /**
+     * Indicates that the [access grant](https://docs.seam.co/use-cases/granting-access) is being deleted.
+     */
+    {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'being_deleted';
-    } | {
+    } /**
+   * Indicates that the access grant should have access to more locations than it currently does. Access methods are being created for the missing locations.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'underprovisioned_access';
-    } | {
+    } /**
+   * Indicates that the access grant has access to locations it should not have. Access methods are being removed from the extra locations.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * Devices whose access codes could not be revoked during reconciliation. Present when the provider does not support revoking an offline access code (e.g. Dormakaba oracode with exhausted override budget).
+         */
         failed_devices?: Array<{
+            /**
+             * Device whose access code could not be revoked.
+             */
             device_id: string;
+            /**
+             * Reason the access code could not be revoked (e.g. `offline_access_code_not_revocable`).
+             */
             error_code: string;
+            /**
+             * Human-readable description of why revocation failed.
+             */
             message: string;
         }> | undefined;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'overprovisioned_access';
-    } | {
+    } /**
+   * Indicates that the access times for this [access grant](https://docs.seam.co/use-cases/granting-access) are being updated.
+   */ | {
+        /**
+         * IDs of the access methods being updated.
+         */
         access_method_ids: Array<string>;
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'updating_access_times';
-    } | {
+    } /**
+   * Indicates that the requested PIN code was already in use on a device, so a different code was assigned.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * ID of the device where the requested code was unavailable.
+         */
         device_id: string;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * The new PIN code that was assigned instead.
+         */
         new_code: string;
+        /**
+         * The originally requested PIN code that was unavailable.
+         */
         original_code: string;
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'requested_code_unavailable';
-    } | {
+    } /**
+   * Indicates that a device in the access grant does not support access codes and was excluded from code materialization.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * ID of the device that does not support access codes.
+         */
         device_id: string;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'device_does_not_support_access_codes';
-    } | {
+    } /**
+   * Indicates that a device in the access grant cannot program an access code for the grant's time range because of device-specific time constraints.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * ID of the device whose time constraints the access grant violates.
+         */
         device_id: string;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * Specific reason why the grant's times are not programmable on the device.
+         */
         reason: 'duration_exceeds_max' | 'times_do_not_match_slots' | 'ongoing_not_supported';
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'device_time_constraints_violated';
     }>;
+    /**
+     * ID of the Seam workspace associated with the Access Grant.
+     */
     workspace_id: string;
 };

package/lib/seam/connect/resources/access-method.d.ts

@@ -1,73 +1,269 @@
+/**
+ * Represents an access method for an Access Grant. Access methods describe the modes of access, such as PIN codes, plastic cards, and mobile keys. For a mobile key, the access method also stores the URL for the associated Instant Key.
+ */
 export type AccessMethod = {
+    /**
+     * ID of the access method.
+     */
     access_method_id: string;
+    /**
+     * Token of the client session associated with the access method.
+     */
     client_session_token?: string | undefined;
+    /**
+     * The actual PIN code for code access methods.
+     */
     code?: string | null | undefined;
+    /**
+     * Date and time at which the access method was created.
+     */
     created_at: string;
+    /**
+     * ID of the customization profile associated with the access method.
+     */
     customization_profile_id?: string | undefined;
+    /**
+     * Display name of the access method.
+     */
     display_name: string;
-    errors: Array<{
+    /**
+     * Errors associated with the [access method](https://docs.seam.co/use-cases/granting-access/creating-an-access-grant).
+     */
+    errors: Array<
+    /**
+     * Indicates that Seam was unable to issue this [access method](https://docs.seam.co/use-cases/granting-access/creating-an-access-grant) before its access grant started, so the recipient may be unable to access the space. This usually points to a problem that needs attention, such as an offline or disconnected device. Seam keeps retrying, and this error clears automatically if the access method is eventually issued.
+     */
+    {
+        /**
+         * Date and time at which Seam created the error.
+         */
         created_at: string;
+        /**
+         * Unique identifier of the type of error. Enables quick recognition and categorization of the issue.
+         */
         error_code: 'failed_to_issue';
+        /**
+         * Detailed description of the error. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
     }>;
+    /**
+     * URL of the Instant Key for mobile key access methods.
+     */
     instant_key_url?: string | undefined;
+    /**
+     * Indicates whether an existing card credential must be assigned to this access method before it can be issued. Only applies to card-mode access methods on systems that support credential assignment.
+     */
     is_assignment_required?: boolean | undefined;
+    /**
+     * Indicates whether encoding with an card encoder is required to issue or reissue the plastic card associated with the access method.
+     */
     is_encoding_required?: boolean | undefined;
+    /**
+     * Indicates whether the access method has been issued.
+     */
     is_issued: boolean;
+    /**
+     * Indicates whether the access method is ready for card assignment. This is true when the access method is in card mode, has not yet been issued, and the system supports credential assignment.
+     */
     is_ready_for_assignment?: boolean | undefined;
+    /**
+     * Indicates whether the access method is ready to be encoded. This is true when the credential has been created and the card has not yet been issued.
+     */
     is_ready_for_encoding?: boolean | undefined;
+    /**
+     * Date and time at which the access method was issued.
+     */
     issued_at: string | null;
+    /**
+     * Access method mode. Supported values: `code`, `card`, `mobile_key`, `cloud_key`.
+     */
     mode: 'code' | 'card' | 'mobile_key' | 'cloud_key';
-    pending_mutations: Array<{
+    /**
+     * Pending mutations for the [access method](https://docs.seam.co/use-cases/granting-access/creating-an-access-grant). Indicates operations that are in progress.
+     */
+    pending_mutations: Array<
+    /**
+     * Seam is in the process of provisioning access for this access method on new devices.
+     */
+    {
+        /**
+         * Date and time at which the mutation was created.
+         */
         created_at: string;
+        /**
+         * Previous device configuration.
+         */
         from: {
+            /**
+             * Previous device IDs where access was provisioned.
+             */
             device_ids: Array<string>;
         };
+        /**
+         * Detailed description of the mutation.
+         */
         message: string;
+        /**
+         * Mutation code to indicate that Seam is in the process of provisioning access for this access method on new devices.
+         */
         mutation_code: 'provisioning_access';
+        /**
+         * New device configuration.
+         */
         to: {
+            /**
+             * New device IDs where access is being provisioned.
+             */
             device_ids: Array<string>;
         };
-    } | {
+    } /**
+   * Seam is in the process of revoking access for this access method from devices.
+   */ | {
+        /**
+         * Date and time at which the mutation was created.
+         */
         created_at: string;
+        /**
+         * Previous device configuration.
+         */
         from: {
+            /**
+             * Previous device IDs where access existed.
+             */
             device_ids: Array<string>;
         };
+        /**
+         * Detailed description of the mutation.
+         */
         message: string;
+        /**
+         * Mutation code to indicate that Seam is in the process of revoking access for this access method from devices.
+         */
         mutation_code: 'revoking_access';
+        /**
+         * New device configuration.
+         */
         to: {
+            /**
+             * New device IDs where access should remain.
+             */
             device_ids: Array<string>;
         };
-    } | {
+    } /**
+   * Seam is in the process of updating the access times for this access method.
+   */ | {
+        /**
+         * Date and time at which the mutation was created.
+         */
         created_at: string;
+        /**
+         * Previous access time configuration.
+         */
         from: {
+            /**
+             * Previous end time for access.
+             */
             ends_at: string | null;
+            /**
+             * Previous start time for access.
+             */
             starts_at: string | null;
         };
+        /**
+         * Detailed description of the mutation.
+         */
         message: string;
+        /**
+         * Mutation code to indicate that Seam is in the process of updating the access times for this access method.
+         */
         mutation_code: 'updating_access_times';
+        /**
+         * New access time configuration.
+         */
         to: {
+            /**
+             * New end time for access.
+             */
             ends_at: string | null;
+            /**
+             * New start time for access.
+             */
             starts_at: string | null;
         };
     }>;
-    warnings: Array<{
+    /**
+     * Warnings associated with the [access method](https://docs.seam.co/use-cases/granting-access/creating-an-access-grant).
+     */
+    warnings: Array<
+    /**
+     * Indicates that the [access method](https://docs.seam.co/use-cases/granting-access/creating-an-access-grant) is being deleted.
+     */
+    {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'being_deleted';
-    } | {
+    } /**
+   * Indicates that the access times for this [access method](https://docs.seam.co/use-cases/granting-access/creating-an-access-grant) are being updated.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'updating_access_times';
-    } | {
+    } /**
+   * Indicates that all attempts to create an access code on this device before the start time failed and a backup access code was used to ensure access was provided in time.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * ID of the original access method from which this backup access method was split, if applicable.
+         */
         original_access_method_id?: string | undefined;
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'pulled_backup_access_code';
-    } | {
+    } /**
+   * Indicates that Seam has not yet issued this [access method](https://docs.seam.co/use-cases/granting-access/creating-an-access-grant), even though its access grant is about to begin, so access may not be ready when the recipient arrives. Seam is still attempting to issue it, and this warning clears automatically once issuance succeeds.
+   */ | {
+        /**
+         * Date and time at which Seam created the warning.
+         */
         created_at: string;
+        /**
+         * Detailed description of the warning. Provides insights into the issue and potentially how to rectify it.
+         */
         message: string;
+        /**
+         * Unique identifier of the type of warning. Enables quick recognition and categorization of the issue.
+         */
         warning_code: 'delay_in_issuing';
     }>;
+    /**
+     * ID of the Seam workspace associated with the access method.
+     */
     workspace_id: string;
 };