@seamapi/http 2.1.0 → 2.3.0

package/src/lib/routes/acs/credentials/credentials.ts

@@ -0,0 +1,569 @@
+/*
+ * 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 { AcsCredential } from 'lib/resources/acs-credential.js'
+import type { AcsEntrance } from 'lib/resources/acs-entrance.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'
+
+export class SeamHttpAcsCredentials {
+  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'> = {},
+  ): SeamHttpAcsCredentials {
+    const constructorOptions = { ...options, client }
+    if (!isSeamHttpOptionsWithClient(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError('Missing client')
+    }
+    return new SeamHttpAcsCredentials(constructorOptions)
+  }
+
+  static fromApiKey(
+    apiKey: SeamHttpOptionsWithApiKey['apiKey'],
+    options: Omit<SeamHttpOptionsWithApiKey, 'apiKey'> = {},
+  ): SeamHttpAcsCredentials {
+    const constructorOptions = { ...options, apiKey }
+    if (!isSeamHttpOptionsWithApiKey(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError('Missing apiKey')
+    }
+    return new SeamHttpAcsCredentials(constructorOptions)
+  }
+
+  static fromClientSessionToken(
+    clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'],
+    options: Omit<
+      SeamHttpOptionsWithClientSessionToken,
+      'clientSessionToken'
+    > = {},
+  ): SeamHttpAcsCredentials {
+    const constructorOptions = { ...options, clientSessionToken }
+    if (!isSeamHttpOptionsWithClientSessionToken(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError('Missing clientSessionToken')
+    }
+    return new SeamHttpAcsCredentials(constructorOptions)
+  }
+
+  static async fromPublishableKey(
+    publishableKey: string,
+    userIdentifierKey: string,
+    options: SeamHttpFromPublishableKeyOptions = {},
+  ): Promise<SeamHttpAcsCredentials> {
+    warnOnInsecureuserIdentifierKey(userIdentifierKey)
+    const clientOptions = parseOptions({ ...options, publishableKey })
+    if (isSeamHttpOptionsWithClient(clientOptions)) {
+      throw new SeamHttpInvalidOptionsError(
+        'The client option cannot be used with SeamHttpAcsCredentials.fromPublishableKey',
+      )
+    }
+    const client = createClient(clientOptions)
+    const clientSessions = SeamHttpClientSessions.fromClient(client)
+    const { token } = await clientSessions.getOrCreate({
+      user_identifier_key: userIdentifierKey,
+    })
+    return SeamHttpAcsCredentials.fromClientSessionToken(token, options)
+  }
+
+  static fromConsoleSessionToken(
+    consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'],
+    workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'],
+    options: Omit<
+      SeamHttpOptionsWithConsoleSessionToken,
+      'consoleSessionToken' | 'workspaceId'
+    > = {},
+  ): SeamHttpAcsCredentials {
+    const constructorOptions = { ...options, consoleSessionToken, workspaceId }
+    if (!isSeamHttpOptionsWithConsoleSessionToken(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError(
+        'Missing consoleSessionToken or workspaceId',
+      )
+    }
+    return new SeamHttpAcsCredentials(constructorOptions)
+  }
+
+  static fromPersonalAccessToken(
+    personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'],
+    workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'],
+    options: Omit<
+      SeamHttpOptionsWithPersonalAccessToken,
+      'personalAccessToken' | 'workspaceId'
+    > = {},
+  ): SeamHttpAcsCredentials {
+    const constructorOptions = { ...options, personalAccessToken, workspaceId }
+    if (!isSeamHttpOptionsWithPersonalAccessToken(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError(
+        'Missing personalAccessToken or workspaceId',
+      )
+    }
+    return new SeamHttpAcsCredentials(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()
+  }
+
+  /**
+   * Assigns a specified [credential](https://docs.seam.co/low-level-apis/access-systems/managing-credentials) to a specified [access system user](https://docs.seam.co/low-level-apis/access-systems/user-management).
+   */
+  assign(
+    parameters: AcsCredentialsAssignParameters,
+    options: AcsCredentialsAssignOptions = {},
+  ): AcsCredentialsAssignRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/acs/credentials/assign',
+      method: 'PATCH',
+      body: parameters,
+      responseKey: undefined,
+      options,
+    })
+  }
+
+  /**
+   * Creates a new [credential](https://docs.seam.co/low-level-apis/managing-credentials) for a specified [ACS user](https://docs.seam.co/low-level-apis/access-systems/user-management). For granting access, we recommend [Access Grants](https://docs.seam.co/use-cases/granting-access) instead: they create and manage the underlying credentials for you, across access systems and standalone smart locks alike. Use this low-level endpoint only when you need direct control over an individual ACS credential.
+   */
+  create(
+    parameters: AcsCredentialsCreateParameters,
+    options: AcsCredentialsCreateOptions = {},
+  ): AcsCredentialsCreateRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/acs/credentials/create',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'acs_credential',
+      options,
+    })
+  }
+
+  /**
+   * Deletes a specified [credential](https://docs.seam.co/low-level-apis/access-systems/managing-credentials).
+   */
+  delete(
+    parameters: AcsCredentialsDeleteParameters,
+    options: AcsCredentialsDeleteOptions = {},
+  ): AcsCredentialsDeleteRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/acs/credentials/delete',
+      method: 'POST',
+      body: parameters,
+      responseKey: undefined,
+      options,
+    })
+  }
+
+  /**
+   * Returns a specified [credential](https://docs.seam.co/low-level-apis/access-systems/managing-credentials).
+   */
+  get(
+    parameters: AcsCredentialsGetParameters,
+    options: AcsCredentialsGetOptions = {},
+  ): AcsCredentialsGetRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/acs/credentials/get',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'acs_credential',
+      options,
+    })
+  }
+
+  /**
+   * Returns a list of all [credentials](https://docs.seam.co/low-level-apis/access-systems/managing-credentials).
+   */
+  list(
+    parameters?: AcsCredentialsListParameters,
+    options: AcsCredentialsListOptions = {},
+  ): AcsCredentialsListRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/acs/credentials/list',
+      method: 'GET',
+      params: parameters,
+      responseKey: 'acs_credentials',
+      options,
+    })
+  }
+
+  /**
+   * Returns a list of all [entrances](https://docs.seam.co/api/acs/entrances) to which a [credential](https://docs.seam.co/api/acs/credentials) grants access.
+   */
+  listAccessibleEntrances(
+    parameters: AcsCredentialsListAccessibleEntrancesParameters,
+    options: AcsCredentialsListAccessibleEntrancesOptions = {},
+  ): AcsCredentialsListAccessibleEntrancesRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/acs/credentials/list_accessible_entrances',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'acs_entrances',
+      options,
+    })
+  }
+
+  /**
+   * Unassigns a specified [credential](https://docs.seam.co/low-level-apis/access-systems/managing-credentials) from a specified [access system user](https://docs.seam.co/low-level-apis/access-systems/user-management).
+   */
+  unassign(
+    parameters: AcsCredentialsUnassignParameters,
+    options: AcsCredentialsUnassignOptions = {},
+  ): AcsCredentialsUnassignRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/acs/credentials/unassign',
+      method: 'PATCH',
+      body: parameters,
+      responseKey: undefined,
+      options,
+    })
+  }
+
+  /**
+   * Updates the code and ends at date and time for a specified [credential](https://docs.seam.co/low-level-apis/access-systems/managing-credentials).
+   */
+  update(
+    parameters: AcsCredentialsUpdateParameters,
+    options: AcsCredentialsUpdateOptions = {},
+  ): AcsCredentialsUpdateRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/acs/credentials/update',
+      method: 'PATCH',
+      body: parameters,
+      responseKey: undefined,
+      options,
+    })
+  }
+}
+
+export type AcsCredentialsAssignParameters = {
+  /**
+   * ID of the credential that you want to assign to an access system user.
+   */
+  acs_credential_id: string
+
+  /**
+   * ID of the access system user to whom you want to assign a credential. You can only provide one of acs_user_id or user_identity_id.
+   */
+  acs_user_id?: string | undefined
+  /**
+   * ID of the user identity to whom you want to assign a credential. You can only provide one of acs_user_id or user_identity_id. If the ACS system contains an ACS user with the same `email_address` or `phone_number` as the user identity that you specify, they are linked, and the credential belongs to the ACS user. If the ACS system does not have a corresponding ACS user, one is created.
+   */
+  user_identity_id?: string | undefined
+}
+
+/**
+ * @deprecated Use AcsCredentialsAssignRequest instead.
+ */
+export type AcsCredentialsAssignResponse = void
+
+export type AcsCredentialsAssignRequest = SeamHttpRequest<void, undefined>
+
+export interface AcsCredentialsAssignOptions {}
+
+export type AcsCredentialsCreateParameters = {
+  /**
+   * Access method for the new credential. Supported values: `code`, `card`, `mobile_key`, `cloud_key`.
+   */
+  access_method: 'code' | 'card' | 'mobile_key' | 'cloud_key'
+
+  /**
+   * ID of the access system to which the new credential belongs. You must provide either `acs_user_id` or the combination of `user_identity_id` and `acs_system_id`.
+   */
+  acs_system_id?: string | undefined
+  /**
+   * ID of the access system user to whom the new credential belongs. You must provide either `acs_user_id` or the combination of `user_identity_id` and `acs_system_id`.
+   */
+  acs_user_id?: string | undefined
+  /**
+   * Set of IDs of the [entrances](https://docs.seam.co/low-level-apis/access-systems/retrieving-entrance-details) for which the new credential grants access.
+   */
+  allowed_acs_entrance_ids?: Array<string> | undefined
+  /**
+   * Vostio-specific metadata for the new credential.
+   */
+  assa_abloy_vostio_metadata?:
+    | {
+        auto_join?: boolean | undefined
+
+        join_all_guest_acs_entrances?: boolean | undefined
+
+        override_all_guest_acs_entrances?: boolean | undefined
+
+        override_guest_acs_entrance_ids?: Array<string> | undefined
+      }
+    | undefined
+  /**
+   * Access (PIN) code for the new credential. There may be manufacturer-specific code restrictions. For details, see the applicable [device or system integration guide](https://docs.seam.co/device-and-system-integration-guides).
+   */
+  code?: string | undefined
+  /**
+   * ACS system ID of the credential manager for the new credential.
+   */
+  credential_manager_acs_system_id?: string | undefined
+  /**
+   * Date and time at which the validity of the new credential 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
+  /**
+   * Indicates whether the new credential is a [multi-phone sync credential](https://docs.seam.co/capability-guides/mobile-access/issuing-mobile-credentials-from-an-access-control-system#what-are-multi-phone-sync-credentials).
+   */
+  is_multi_phone_sync_credential?: boolean | undefined
+  /**
+   * Salto Space-specific metadata for the new credential.
+   */
+  salto_space_metadata?:
+    | {
+        /**
+         * Indicates whether to assign a first, new card to a user. See also [Programming Salto Space Card-based Credentials](https://docs.seam.co/device-and-system-integration-guides/salto-proaccess-space-access-system/programming-salto-space-card-based-credentials).
+         */
+        assign_new_key?: boolean | undefined
+      }
+    | undefined
+  /**
+   * Date and time at which the validity of the new credential starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
+   */
+  starts_at?: string | undefined
+  /**
+   * ID of the user identity to whom the new credential belongs. You must provide either `acs_user_id` or the combination of `user_identity_id` and `acs_system_id`. If the access system contains a user with the same `email_address` or `phone_number` as the user identity that you specify, they are linked, and the credential belongs to the access system user. If the access system does not have a corresponding user, one is created.
+   */
+  user_identity_id?: string | undefined
+  /**
+   * Visionline-specific metadata for the new credential.
+   */
+  visionline_metadata?:
+    | {
+        auto_join?: boolean | undefined
+
+        card_format?: 'TLCode' | 'rfid48' | undefined
+
+        card_function_type?: 'guest' | 'staff' | undefined
+
+        joiner_acs_credential_ids?: Array<string> | undefined
+
+        override?: boolean | undefined
+      }
+    | undefined
+}
+
+/**
+ * @deprecated Use AcsCredentialsCreateRequest instead.
+ */
+export type AcsCredentialsCreateResponse = { acs_credential: AcsCredential }
+
+export type AcsCredentialsCreateRequest = SeamHttpRequest<
+  AcsCredentialsCreateResponse,
+  'acs_credential'
+>
+
+export interface AcsCredentialsCreateOptions {}
+
+export type AcsCredentialsDeleteParameters = {
+  /**
+   * ID of the credential that you want to delete.
+   */
+  acs_credential_id: string
+}
+
+/**
+ * @deprecated Use AcsCredentialsDeleteRequest instead.
+ */
+export type AcsCredentialsDeleteResponse = void
+
+export type AcsCredentialsDeleteRequest = SeamHttpRequest<void, undefined>
+
+export interface AcsCredentialsDeleteOptions {}
+
+export type AcsCredentialsGetParameters = {
+  /**
+   * ID of the credential that you want to get.
+   */
+  acs_credential_id: string
+}
+
+/**
+ * @deprecated Use AcsCredentialsGetRequest instead.
+ */
+export type AcsCredentialsGetResponse = { acs_credential: AcsCredential }
+
+export type AcsCredentialsGetRequest = SeamHttpRequest<
+  AcsCredentialsGetResponse,
+  'acs_credential'
+>
+
+export interface AcsCredentialsGetOptions {}
+
+export type AcsCredentialsListParameters = {
+  /**
+   * ID of the access system user for which you want to retrieve all credentials.
+   */
+  acs_user_id?: string | undefined
+  /**
+   * ID of the access system for which you want to retrieve all credentials.
+   */
+  acs_system_id?: string | undefined
+  /**
+   * ID of the user identity for which you want to retrieve all credentials.
+   */
+  user_identity_id?: string | undefined
+  /**
+   * Date and time, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format, before which events to return were created.
+   */
+  created_before?: string | undefined
+  /**
+   * Indicates whether you want to retrieve only multi-phone sync credentials or non-multi-phone sync credentials.
+   */
+  is_multi_phone_sync_credential?: boolean | undefined
+  /**
+   * Number of credentials 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
+  /**
+   * String for which to search. Filters returned credentials to include all records that satisfy a partial match using `display_name`, `code`, `card_number`, `acs_user_id` or `acs_credential_id`.
+   */
+  search?: string | undefined
+}
+
+/**
+ * @deprecated Use AcsCredentialsListRequest instead.
+ */
+export type AcsCredentialsListResponse = {
+  acs_credentials: Array<AcsCredential>
+}
+
+export type AcsCredentialsListRequest = SeamHttpRequest<
+  AcsCredentialsListResponse,
+  'acs_credentials'
+>
+
+export interface AcsCredentialsListOptions {}
+
+export type AcsCredentialsListAccessibleEntrancesParameters = {
+  /**
+   * ID of the credential for which you want to retrieve all entrances to which the credential grants access.
+   */
+  acs_credential_id: string
+}
+
+/**
+ * @deprecated Use AcsCredentialsListAccessibleEntrancesRequest instead.
+ */
+export type AcsCredentialsListAccessibleEntrancesResponse = {
+  acs_entrances: Array<AcsEntrance>
+}
+
+export type AcsCredentialsListAccessibleEntrancesRequest = SeamHttpRequest<
+  AcsCredentialsListAccessibleEntrancesResponse,
+  'acs_entrances'
+>
+
+export interface AcsCredentialsListAccessibleEntrancesOptions {}
+
+export type AcsCredentialsUnassignParameters = {
+  /**
+   * ID of the credential that you want to unassign from an access system user.
+   */
+  acs_credential_id: string
+
+  /**
+   * ID of the access system user from which you want to unassign a credential. You can only provide one of acs_user_id or user_identity_id.
+   */
+  acs_user_id?: string | undefined
+  /**
+   * ID of the user identity from which you want to unassign a credential. You can only provide one of acs_user_id or user_identity_id.
+   */
+  user_identity_id?: string | undefined
+}
+
+/**
+ * @deprecated Use AcsCredentialsUnassignRequest instead.
+ */
+export type AcsCredentialsUnassignResponse = void
+
+export type AcsCredentialsUnassignRequest = SeamHttpRequest<void, undefined>
+
+export interface AcsCredentialsUnassignOptions {}
+
+export type AcsCredentialsUpdateParameters = {
+  /**
+   * ID of the credential that you want to update.
+   */
+  acs_credential_id: string
+
+  /**
+   * Replacement access (PIN) code for the credential that you want to update.
+   */
+  code?: string | undefined
+  /**
+   * Replacement date and time at which the validity of the credential 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 the `starts_at` value that you set when creating the credential.
+   */
+  ends_at?: string | undefined
+}
+
+/**
+ * @deprecated Use AcsCredentialsUpdateRequest instead.
+ */
+export type AcsCredentialsUpdateResponse = void
+
+export type AcsCredentialsUpdateRequest = SeamHttpRequest<void, undefined>
+
+export interface AcsCredentialsUpdateOptions {}