@seamapi/http 2.1.0 → 2.3.0

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

@@ -0,0 +1,640 @@
+/*
+ * Automatically generated by codegen/smith.ts.
+ * Do not edit this file or add other files to this directory.
+ */
+
+import {
+  getAuthHeadersForClientSessionToken,
+  warnOnInsecureuserIdentifierKey,
+} from 'lib/auth.js'
+import { type Client, createClient } from 'lib/client.js'
+import { seamApiLtsVersion } from 'lib/lts-version.js'
+import {
+  isSeamHttpOptionsWithApiKey,
+  isSeamHttpOptionsWithClient,
+  isSeamHttpOptionsWithClientSessionToken,
+  isSeamHttpOptionsWithConsoleSessionToken,
+  isSeamHttpOptionsWithPersonalAccessToken,
+  type SeamHttpFromPublishableKeyOptions,
+  SeamHttpInvalidOptionsError,
+  type SeamHttpOptions,
+  type SeamHttpOptionsWithApiKey,
+  type SeamHttpOptionsWithClient,
+  type SeamHttpOptionsWithClientSessionToken,
+  type SeamHttpOptionsWithConsoleSessionToken,
+  type SeamHttpOptionsWithPersonalAccessToken,
+  type SeamHttpRequestOptions,
+} from 'lib/options.js'
+import {
+  limitToSeamHttpRequestOptions,
+  parseOptions,
+} from 'lib/parse-options.js'
+import type { AccessGrant } from 'lib/resources/access-grant.js'
+import type { Batch } from 'lib/resources/batch.js'
+import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js'
+import { SeamHttpRequest } from 'lib/seam-http-request.js'
+import { SeamPaginator } from 'lib/seam-paginator.js'
+
+import { SeamHttpAccessGrantsUnmanaged } from './unmanaged/index.js'
+
+export class SeamHttpAccessGrants {
+  client: Client
+  readonly defaults: Required<SeamHttpRequestOptions>
+  readonly ltsVersion = seamApiLtsVersion
+  static ltsVersion = seamApiLtsVersion
+
+  constructor(apiKeyOrOptions: string | SeamHttpOptions = {}) {
+    const options = parseOptions(apiKeyOrOptions)
+    this.client = 'client' in options ? options.client : createClient(options)
+    this.defaults = limitToSeamHttpRequestOptions(options)
+  }
+
+  static fromClient(
+    client: SeamHttpOptionsWithClient['client'],
+    options: Omit<SeamHttpOptionsWithClient, 'client'> = {},
+  ): SeamHttpAccessGrants {
+    const constructorOptions = { ...options, client }
+    if (!isSeamHttpOptionsWithClient(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError('Missing client')
+    }
+    return new SeamHttpAccessGrants(constructorOptions)
+  }
+
+  static fromApiKey(
+    apiKey: SeamHttpOptionsWithApiKey['apiKey'],
+    options: Omit<SeamHttpOptionsWithApiKey, 'apiKey'> = {},
+  ): SeamHttpAccessGrants {
+    const constructorOptions = { ...options, apiKey }
+    if (!isSeamHttpOptionsWithApiKey(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError('Missing apiKey')
+    }
+    return new SeamHttpAccessGrants(constructorOptions)
+  }
+
+  static fromClientSessionToken(
+    clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'],
+    options: Omit<
+      SeamHttpOptionsWithClientSessionToken,
+      'clientSessionToken'
+    > = {},
+  ): SeamHttpAccessGrants {
+    const constructorOptions = { ...options, clientSessionToken }
+    if (!isSeamHttpOptionsWithClientSessionToken(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError('Missing clientSessionToken')
+    }
+    return new SeamHttpAccessGrants(constructorOptions)
+  }
+
+  static async fromPublishableKey(
+    publishableKey: string,
+    userIdentifierKey: string,
+    options: SeamHttpFromPublishableKeyOptions = {},
+  ): Promise<SeamHttpAccessGrants> {
+    warnOnInsecureuserIdentifierKey(userIdentifierKey)
+    const clientOptions = parseOptions({ ...options, publishableKey })
+    if (isSeamHttpOptionsWithClient(clientOptions)) {
+      throw new SeamHttpInvalidOptionsError(
+        'The client option cannot be used with SeamHttpAccessGrants.fromPublishableKey',
+      )
+    }
+    const client = createClient(clientOptions)
+    const clientSessions = SeamHttpClientSessions.fromClient(client)
+    const { token } = await clientSessions.getOrCreate({
+      user_identifier_key: userIdentifierKey,
+    })
+    return SeamHttpAccessGrants.fromClientSessionToken(token, options)
+  }
+
+  static fromConsoleSessionToken(
+    consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'],
+    workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'],
+    options: Omit<
+      SeamHttpOptionsWithConsoleSessionToken,
+      'consoleSessionToken' | 'workspaceId'
+    > = {},
+  ): SeamHttpAccessGrants {
+    const constructorOptions = { ...options, consoleSessionToken, workspaceId }
+    if (!isSeamHttpOptionsWithConsoleSessionToken(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError(
+        'Missing consoleSessionToken or workspaceId',
+      )
+    }
+    return new SeamHttpAccessGrants(constructorOptions)
+  }
+
+  static fromPersonalAccessToken(
+    personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'],
+    workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'],
+    options: Omit<
+      SeamHttpOptionsWithPersonalAccessToken,
+      'personalAccessToken' | 'workspaceId'
+    > = {},
+  ): SeamHttpAccessGrants {
+    const constructorOptions = { ...options, personalAccessToken, workspaceId }
+    if (!isSeamHttpOptionsWithPersonalAccessToken(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError(
+        'Missing personalAccessToken or workspaceId',
+      )
+    }
+    return new SeamHttpAccessGrants(constructorOptions)
+  }
+
+  createPaginator<const TResponse, const TResponseKey extends keyof TResponse>(
+    request: SeamHttpRequest<TResponse, TResponseKey>,
+  ): SeamPaginator<TResponse, TResponseKey> {
+    return new SeamPaginator<TResponse, TResponseKey>(this, request)
+  }
+
+  async updateClientSessionToken(
+    clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'],
+  ): Promise<void> {
+    const { headers } = this.client.defaults
+    const authHeaders = getAuthHeadersForClientSessionToken({
+      clientSessionToken,
+    })
+    for (const key of Object.keys(authHeaders)) {
+      if (headers[key] == null) {
+        throw new Error(
+          'Cannot update a clientSessionToken on a client created without a clientSessionToken',
+        )
+      }
+    }
+    this.client.defaults.headers = { ...headers, ...authHeaders }
+    const clientSessions = SeamHttpClientSessions.fromClient(this.client)
+    await clientSessions.get()
+  }
+
+  get unmanaged(): SeamHttpAccessGrantsUnmanaged {
+    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 = {},
+  ): AccessGrantsCreateRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_grants/create',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'access_grant',
+      options,
+    })
+  }
+
+  /**
+   * Delete an Access Grant.
+   */
+  delete(
+    parameters: AccessGrantsDeleteParameters,
+    options: AccessGrantsDeleteOptions = {},
+  ): AccessGrantsDeleteRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_grants/delete',
+      method: 'POST',
+      body: parameters,
+      responseKey: undefined,
+      options,
+    })
+  }
+
+  /**
+   * Get an Access Grant.
+   */
+  get(
+    parameters?: AccessGrantsGetParameters,
+    options: AccessGrantsGetOptions = {},
+  ): AccessGrantsGetRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_grants/get',
+      method: 'GET',
+      params: parameters,
+      responseKey: 'access_grant',
+      options,
+    })
+  }
+
+  /**
+   * Gets all related resources for one or more Access Grants.
+   */
+  getRelated(
+    parameters?: AccessGrantsGetRelatedParameters,
+    options: AccessGrantsGetRelatedOptions = {},
+  ): AccessGrantsGetRelatedRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_grants/get_related',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'batch',
+      options,
+    })
+  }
+
+  /**
+   * Gets an Access Grant.
+   */
+  list(
+    parameters?: AccessGrantsListParameters,
+    options: AccessGrantsListOptions = {},
+  ): AccessGrantsListRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_grants/list',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'access_grants',
+      options,
+    })
+  }
+
+  /**
+   * Adds additional requested access methods to an existing Access Grant.
+   */
+  requestAccessMethods(
+    parameters: AccessGrantsRequestAccessMethodsParameters,
+    options: AccessGrantsRequestAccessMethodsOptions = {},
+  ): AccessGrantsRequestAccessMethodsRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_grants/request_access_methods',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'access_grant',
+      options,
+    })
+  }
+
+  /**
+   * Updates an existing Access Grant's time window.
+   */
+  update(
+    parameters?: AccessGrantsUpdateParameters,
+    options: AccessGrantsUpdateOptions = {},
+  ): AccessGrantsUpdateRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_grants/update',
+      method: 'PATCH',
+      body: parameters,
+      responseKey: undefined,
+      options,
+    })
+  }
+}
+
+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
+}
+
+/**
+ * @deprecated Use AccessGrantsCreateRequest instead.
+ */
+export type AccessGrantsCreateResponse = { access_grant: AccessGrant }
+
+export type AccessGrantsCreateRequest = SeamHttpRequest<
+  AccessGrantsCreateResponse,
+  'access_grant'
+>
+
+export interface AccessGrantsCreateOptions {}
+
+export type AccessGrantsDeleteParameters = {
+  /**
+   * ID of Access Grant to delete.
+   */
+  access_grant_id: string
+}
+
+/**
+ * @deprecated Use AccessGrantsDeleteRequest instead.
+ */
+export type AccessGrantsDeleteResponse = void
+
+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
+}
+
+/**
+ * @deprecated Use AccessGrantsGetRequest instead.
+ */
+export type AccessGrantsGetResponse = { access_grant: AccessGrant }
+
+export type AccessGrantsGetRequest = SeamHttpRequest<
+  AccessGrantsGetResponse,
+  'access_grant'
+>
+
+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'
+        | 'devices'
+        | 'acs_entrances'
+        | 'connected_accounts'
+        | 'acs_systems'
+        | 'user_identities'
+        | 'acs_access_groups'
+        | 'access_methods'
+      >
+    | undefined
+
+  include?:
+    | Array<
+        | 'spaces'
+        | 'devices'
+        | 'acs_entrances'
+        | 'connected_accounts'
+        | 'acs_systems'
+        | 'user_identities'
+        | 'acs_access_groups'
+        | 'access_methods'
+      >
+    | undefined
+}
+
+/**
+ * @deprecated Use AccessGrantsGetRelatedRequest instead.
+ */
+export type AccessGrantsGetRelatedResponse = {
+  batch: Batch<
+    | 'spaces'
+    | 'devices'
+    | 'acs_entrances'
+    | 'connected_accounts'
+    | 'acs_systems'
+    | 'user_identities'
+    | 'acs_access_groups'
+    | 'access_methods'
+  >
+}
+
+export type AccessGrantsGetRelatedRequest = SeamHttpRequest<
+  AccessGrantsGetRelatedResponse,
+  'batch'
+>
+
+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
+}
+
+/**
+ * @deprecated Use AccessGrantsListRequest instead.
+ */
+export type AccessGrantsListResponse = { access_grants: Array<AccessGrant> }
+
+export type AccessGrantsListRequest = SeamHttpRequest<
+  AccessGrantsListResponse,
+  'access_grants'
+>
+
+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
+  }>
+}
+
+/**
+ * @deprecated Use AccessGrantsRequestAccessMethodsRequest instead.
+ */
+export type AccessGrantsRequestAccessMethodsResponse = {
+  access_grant: AccessGrant
+}
+
+export type AccessGrantsRequestAccessMethodsRequest = SeamHttpRequest<
+  AccessGrantsRequestAccessMethodsResponse,
+  'access_grant'
+>
+
+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
+}
+
+/**
+ * @deprecated Use AccessGrantsUpdateRequest instead.
+ */
+export type AccessGrantsUpdateResponse = void
+
+export type AccessGrantsUpdateRequest = SeamHttpRequest<void, undefined>
+
+export interface AccessGrantsUpdateOptions {}