@seamapi/http 2.1.0 → 2.3.0

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

@@ -0,0 +1,523 @@
+/*
+ * 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 { AccessMethod } from 'lib/resources/access-method.js'
+import type { ActionAttempt } from 'lib/resources/action-attempt.js'
+import type { Batch } from 'lib/resources/batch.js'
+import { SeamHttpActionAttempts } from 'lib/routes/action-attempts/index.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 { SeamHttpAccessMethodsUnmanaged } from './unmanaged/index.js'
+
+export class SeamHttpAccessMethods {
+  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'> = {},
+  ): SeamHttpAccessMethods {
+    const constructorOptions = { ...options, client }
+    if (!isSeamHttpOptionsWithClient(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError('Missing client')
+    }
+    return new SeamHttpAccessMethods(constructorOptions)
+  }
+
+  static fromApiKey(
+    apiKey: SeamHttpOptionsWithApiKey['apiKey'],
+    options: Omit<SeamHttpOptionsWithApiKey, 'apiKey'> = {},
+  ): SeamHttpAccessMethods {
+    const constructorOptions = { ...options, apiKey }
+    if (!isSeamHttpOptionsWithApiKey(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError('Missing apiKey')
+    }
+    return new SeamHttpAccessMethods(constructorOptions)
+  }
+
+  static fromClientSessionToken(
+    clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'],
+    options: Omit<
+      SeamHttpOptionsWithClientSessionToken,
+      'clientSessionToken'
+    > = {},
+  ): SeamHttpAccessMethods {
+    const constructorOptions = { ...options, clientSessionToken }
+    if (!isSeamHttpOptionsWithClientSessionToken(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError('Missing clientSessionToken')
+    }
+    return new SeamHttpAccessMethods(constructorOptions)
+  }
+
+  static async fromPublishableKey(
+    publishableKey: string,
+    userIdentifierKey: string,
+    options: SeamHttpFromPublishableKeyOptions = {},
+  ): Promise<SeamHttpAccessMethods> {
+    warnOnInsecureuserIdentifierKey(userIdentifierKey)
+    const clientOptions = parseOptions({ ...options, publishableKey })
+    if (isSeamHttpOptionsWithClient(clientOptions)) {
+      throw new SeamHttpInvalidOptionsError(
+        'The client option cannot be used with SeamHttpAccessMethods.fromPublishableKey',
+      )
+    }
+    const client = createClient(clientOptions)
+    const clientSessions = SeamHttpClientSessions.fromClient(client)
+    const { token } = await clientSessions.getOrCreate({
+      user_identifier_key: userIdentifierKey,
+    })
+    return SeamHttpAccessMethods.fromClientSessionToken(token, options)
+  }
+
+  static fromConsoleSessionToken(
+    consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'],
+    workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'],
+    options: Omit<
+      SeamHttpOptionsWithConsoleSessionToken,
+      'consoleSessionToken' | 'workspaceId'
+    > = {},
+  ): SeamHttpAccessMethods {
+    const constructorOptions = { ...options, consoleSessionToken, workspaceId }
+    if (!isSeamHttpOptionsWithConsoleSessionToken(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError(
+        'Missing consoleSessionToken or workspaceId',
+      )
+    }
+    return new SeamHttpAccessMethods(constructorOptions)
+  }
+
+  static fromPersonalAccessToken(
+    personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'],
+    workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'],
+    options: Omit<
+      SeamHttpOptionsWithPersonalAccessToken,
+      'personalAccessToken' | 'workspaceId'
+    > = {},
+  ): SeamHttpAccessMethods {
+    const constructorOptions = { ...options, personalAccessToken, workspaceId }
+    if (!isSeamHttpOptionsWithPersonalAccessToken(constructorOptions)) {
+      throw new SeamHttpInvalidOptionsError(
+        'Missing personalAccessToken or workspaceId',
+      )
+    }
+    return new SeamHttpAccessMethods(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(): SeamHttpAccessMethodsUnmanaged {
+    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 = {},
+  ): AccessMethodsAssignCardRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_methods/assign_card',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'action_attempt',
+      options,
+      actionAttempts: SeamHttpActionAttempts.fromClient(this.client, {
+        ...this.defaults,
+        waitForActionAttempt: false,
+      }),
+    })
+  }
+
+  /**
+   * Deletes an access method.
+   */
+  delete(
+    parameters?: AccessMethodsDeleteParameters,
+    options: AccessMethodsDeleteOptions = {},
+  ): AccessMethodsDeleteRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_methods/delete',
+      method: 'DELETE',
+      params: parameters,
+      responseKey: undefined,
+      options,
+    })
+  }
+
+  /**
+   * 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 = {},
+  ): AccessMethodsEncodeRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_methods/encode',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'action_attempt',
+      options,
+      actionAttempts: SeamHttpActionAttempts.fromClient(this.client, {
+        ...this.defaults,
+        waitForActionAttempt: false,
+      }),
+    })
+  }
+
+  /**
+   * Gets an access method.
+   */
+  get(
+    parameters: AccessMethodsGetParameters,
+    options: AccessMethodsGetOptions = {},
+  ): AccessMethodsGetRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_methods/get',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'access_method',
+      options,
+    })
+  }
+
+  /**
+   * Gets all related resources for one or more Access Methods.
+   */
+  getRelated(
+    parameters: AccessMethodsGetRelatedParameters,
+    options: AccessMethodsGetRelatedOptions = {},
+  ): AccessMethodsGetRelatedRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_methods/get_related',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'batch',
+      options,
+    })
+  }
+
+  /**
+   * Lists all access methods, usually filtered by Access Grant.
+   */
+  list(
+    parameters?: AccessMethodsListParameters,
+    options: AccessMethodsListOptions = {},
+  ): AccessMethodsListRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_methods/list',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'access_methods',
+      options,
+    })
+  }
+
+  /**
+   * 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 = {},
+  ): AccessMethodsUnlockDoorRequest {
+    return new SeamHttpRequest(this, {
+      pathname: '/access_methods/unlock_door',
+      method: 'POST',
+      body: parameters,
+      responseKey: 'action_attempt',
+      options,
+      actionAttempts: SeamHttpActionAttempts.fromClient(this.client, {
+        ...this.defaults,
+        waitForActionAttempt: false,
+      }),
+    })
+  }
+}
+
+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
+}
+
+/**
+ * @deprecated Use AccessMethodsAssignCardRequest instead.
+ */
+export type AccessMethodsAssignCardResponse = { action_attempt: ActionAttempt }
+
+export type AccessMethodsAssignCardRequest = SeamHttpRequest<
+  AccessMethodsAssignCardResponse,
+  'action_attempt'
+>
+
+export type AccessMethodsAssignCardOptions = Pick<
+  SeamHttpRequestOptions,
+  'waitForActionAttempt'
+>
+
+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
+}
+
+/**
+ * @deprecated Use AccessMethodsDeleteRequest instead.
+ */
+export type AccessMethodsDeleteResponse = void
+
+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
+}
+
+/**
+ * @deprecated Use AccessMethodsEncodeRequest instead.
+ */
+export type AccessMethodsEncodeResponse = { action_attempt: ActionAttempt }
+
+export type AccessMethodsEncodeRequest = SeamHttpRequest<
+  AccessMethodsEncodeResponse,
+  'action_attempt'
+>
+
+export type AccessMethodsEncodeOptions = Pick<
+  SeamHttpRequestOptions,
+  'waitForActionAttempt'
+>
+
+export type AccessMethodsGetParameters = {
+  /**
+   * ID of access method to get.
+   */
+  access_method_id: string
+}
+
+/**
+ * @deprecated Use AccessMethodsGetRequest instead.
+ */
+export type AccessMethodsGetResponse = { access_method: AccessMethod }
+
+export type AccessMethodsGetRequest = SeamHttpRequest<
+  AccessMethodsGetResponse,
+  'access_method'
+>
+
+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?:
+    | Array<
+        | 'spaces'
+        | 'devices'
+        | 'acs_entrances'
+        | 'access_grants'
+        | 'access_methods'
+        | 'instant_keys'
+        | 'client_sessions'
+        | 'acs_credentials'
+      >
+    | undefined
+
+  include?:
+    | Array<
+        | 'spaces'
+        | 'devices'
+        | 'acs_entrances'
+        | 'access_grants'
+        | 'access_methods'
+        | 'instant_keys'
+        | 'client_sessions'
+        | 'acs_credentials'
+      >
+    | undefined
+}
+
+/**
+ * @deprecated Use AccessMethodsGetRelatedRequest instead.
+ */
+export type AccessMethodsGetRelatedResponse = {
+  batch: Batch<
+    | 'spaces'
+    | 'devices'
+    | 'acs_entrances'
+    | 'access_grants'
+    | 'access_methods'
+    | 'instant_keys'
+    | 'client_sessions'
+    | 'acs_credentials'
+  >
+}
+
+export type AccessMethodsGetRelatedRequest = SeamHttpRequest<
+  AccessMethodsGetRelatedResponse,
+  'batch'
+>
+
+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
+}
+
+/**
+ * @deprecated Use AccessMethodsListRequest instead.
+ */
+export type AccessMethodsListResponse = { access_methods: Array<AccessMethod> }
+
+export type AccessMethodsListRequest = SeamHttpRequest<
+  AccessMethodsListResponse,
+  'access_methods'
+>
+
+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
+}
+
+/**
+ * @deprecated Use AccessMethodsUnlockDoorRequest instead.
+ */
+export type AccessMethodsUnlockDoorResponse = { action_attempt: ActionAttempt }
+
+export type AccessMethodsUnlockDoorRequest = SeamHttpRequest<
+  AccessMethodsUnlockDoorResponse,
+  'action_attempt'
+>
+
+export type AccessMethodsUnlockDoorOptions = Pick<
+  SeamHttpRequestOptions,
+  'waitForActionAttempt'
+>