@seamapi/cli 0.0.1 → 0.4.0

package/src/bin/cli.ts

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+import { randomBytes } from 'node:crypto'
+import { isDeepStrictEqual as isEqual } from 'node:util'
+
+import chalk from 'chalk'
+import commandLineUsage from 'command-line-usage'
+import parseArgs, { type ParsedArgs } from 'minimist'
+import prompts from 'prompts'
+
+import { getApiBlueprint } from 'lib/get-api-blueprint.js'
+import { getConfigStore } from 'lib/get-config-store.js'
+import { getServer } from 'lib/get-server.js'
+import { interactForActionAttemptPoll } from 'lib/interact-for-action-attempt-poll.js'
+import { interactForCommandParams } from 'lib/interact-for-command-params.js'
+import { interactForCommandSelection } from 'lib/interact-for-command-selection.js'
+import { interactForLogin } from 'lib/interact-for-login.js'
+import { interactForServerSelection } from 'lib/interact-for-server-selection.js'
+import { interactForUseRemoteApiDefs } from 'lib/interact-for-use-remote-api-defs.js'
+import { interactForWorkspaceId } from 'lib/interact-for-workspace-id.js'
+import type { ContextHelpers } from 'lib/types.js'
+import { RequestSeamApi } from 'lib/util/request-seam-api.js'
+import { validateToken } from 'lib/validate-token.js'
+import seamapiCliVersion from 'lib/version.js'
+
+const sections = [
+  {
+    header: 'Seam CLI',
+    content:
+      'Every seam command is interactive and will prompt you for any missing required properties with helpful suggestions. To avoid automatic behavior, pass -y ',
+  },
+  {
+    header: 'Options',
+    optionList: [
+      {
+        name: 'help',
+        description: 'Display this help guide.',
+        alias: 'h',
+        type: Boolean,
+      },
+    ],
+  },
+  {
+    header: 'Command List Examples',
+    content: [
+      { name: 'seam', summary: 'Interactively select commands to execute.' },
+      { name: 'seam login', summary: 'Login to Seam.' },
+      { name: 'seam select workspace', summary: 'Select your workspace.' },
+      {
+        name: 'seam connect-webviews create',
+        summary: 'Create a connect webview to connect devices.',
+      },
+      { name: 'seam devices list', summary: 'List devices in your workspace.' },
+      {
+        name: 'seam locks unlock-door {bold --device-id} $MY_DOOR',
+        summary: 'Unlock a lock.',
+      },
+      {
+        name: "seam access-codes create {bold --code} '1234' {bold --name} 'My Code'",
+        summary: 'Create an access code.',
+      },
+      {
+        name: 'seam access-codes list {bold --device-id} $MY_DOOR',
+        summary: 'List you access codes.',
+      },
+    ],
+  },
+]
+
+async function cli(args: ParsedArgs) {
+  const config = getConfigStore()
+
+  if (args['help'] || args['h']) {
+    const usage = commandLineUsage(sections)
+    console.log(usage)
+    return
+  }
+
+  if (args['version']) {
+    console.log(seamapiCliVersion)
+    process.exit(0)
+  }
+
+  if (
+    args._[0] === 'config' &&
+    args._[1] === 'set' &&
+    args._[2] === 'fake-server'
+  ) {
+    const randomstring = randomBytes(5).toString('hex')
+    const fakeApiUrl = `https://${randomstring}.fakeseamconnect.seam.vc`
+
+    config.set('server', fakeApiUrl)
+    console.log(`Server URL set to ${fakeApiUrl}`)
+
+    config.set(`${getServer()}.pat`, `seam_apikey1_token`)
+    console.log(`PAT set to use fakeseamconnect with "seam_apikey1_token"`)
+    return
+  }
+
+  if (
+    !config.get(`${getServer()}.pat`) &&
+    args._[0] !== 'login' &&
+    !isEqual(args._, ['select', 'server'])
+  ) {
+    console.log(`Not logged in. Please run "seam login"`)
+    process.exit(1)
+  }
+
+  args._ = args._.map((arg) => arg.toLowerCase().replace(/_/g, '-'))
+  for (const k in args) {
+    args[k.toLowerCase().replace(/-/g, '_')] = args[k]
+  }
+
+  const use_remote_api_defs =
+    args['remote_api_defs'] ?? config.get('use_remote_api_defs')
+
+  const blueprint = await getApiBlueprint(use_remote_api_defs ?? false)
+
+  const commandParams: Record<string, any> = {}
+
+  /**
+   * Whether or not to auto-select first option
+   */
+  const is_interactive = args['y'] !== true
+
+  const ctx: ContextHelpers = {
+    blueprint,
+    is_interactive,
+  }
+
+  for (const k in args) {
+    if (k === '_') continue
+    const v = args[k]
+    delete args[k]
+    args[k.replace(/-/g, '_')] = v
+    commandParams[k.replace(/-/g, '_')] = v
+  }
+
+  const selectedCommand = await interactForCommandSelection(args._, ctx)
+  if (isEqual(selectedCommand, ['login'])) {
+    if (args['server']) {
+      config.set('server', args['server'])
+      config.delete('current_workspace_id')
+    }
+    if (args['token']) {
+      const token = String(args['token']).trim()
+      await validateToken(token, args['workspace_id'])
+      config.set(`${getServer()}.pat`, token)
+      config.delete('current_workspace_id')
+    }
+    if (args['workspace_id']) {
+      config.set(`current_workspace_id`, args['workspace_id'])
+    }
+    if (args['token'] || args['workspace_id'] || args['server']) {
+      return
+    }
+    await interactForLogin()
+    return
+  } else if (isEqual(selectedCommand, ['logout'])) {
+    config.delete('pat')
+    console.log('Logged out!')
+    return
+  } else if (isEqual(selectedCommand, ['config', 'reveal-location'])) {
+    console.log(config.path)
+    return
+  } else if (isEqual(selectedCommand, ['config', 'use-remote-api-defs'])) {
+    await interactForUseRemoteApiDefs()
+    return
+  } else if (isEqual(selectedCommand, ['select', 'workspace'])) {
+    await interactForWorkspaceId()
+    return
+  } else if (isEqual(selectedCommand, ['events', 'list'])) {
+    if (!commandParams['since']) {
+      const date = new Date()
+      date.setMonth(date.getMonth() - 1)
+      commandParams['since'] = date.toISOString()
+    }
+  } else if (isEqual(selectedCommand, ['select', 'server'])) {
+    if (args['server']) {
+      config.set('server', args['server'])
+      config.delete('current_workspace_id')
+      return
+    }
+    await interactForServerSelection()
+    return
+  } else if (isEqual(selectedCommand, ['health', 'get-health'])) {
+    await RequestSeamApi({
+      path: '/health/get_health',
+      params: {},
+    })
+
+    return
+  }
+  // TODO - do this using the OpenAPI spec for the command rather than
+  // explicitly encoding the property names
+  if (commandParams['accepted_providers']) {
+    commandParams['accepted_providers'] =
+      commandParams['accepted_providers'].split(',')
+  }
+
+  // Hit 'back' on a top-level command path, so we start again
+  const lastCommandPath = selectedCommand.slice(-1)[0]
+  if (lastCommandPath === '[Back]') {
+    return await cli({
+      ...args,
+      _: [],
+    })
+  }
+
+  const params = await interactForCommandParams(
+    { command: selectedCommand, params: commandParams },
+    ctx,
+  )
+
+  if (params === '[Back]') {
+    const previousCommands = [...selectedCommand]
+    previousCommands.pop()
+    return await cli({
+      ...args,
+      _: previousCommands,
+    })
+  }
+
+  const apiPath = `/${selectedCommand.join('/').replace(/-/g, '_')}`
+
+  if (apiPath.includes('/events/list') && params.between) {
+    delete params.since
+  }
+
+  const response = await RequestSeamApi({
+    path: apiPath,
+    params,
+  })
+
+  if (response.data?.connect_webview) {
+    await handleConnectWebviewResponse(response.data.connect_webview)
+  }
+
+  if (response.data?.action_attempt) {
+    interactForActionAttemptPoll(response.data.action_attempt)
+  }
+}
+
+const handleConnectWebviewResponse = async (connect_webview: any) => {
+  const url = connect_webview.url
+
+  if (process.env['INSIDE_WEB_BROWSER'] !== '1') {
+    const { action } = await prompts({
+      type: 'confirm',
+      name: 'action',
+      message: 'Would you like to open the webview in your browser?',
+    })
+
+    if (action) {
+      const { default: open } = await import('open')
+      await open(url)
+    }
+  }
+}
+
+cli(parseArgs(process.argv.slice(2), { string: ['code'] })).catch((e) => {
+  console.log(chalk.red(`CLI Error: ${e.toString()}\n${e.stack}`))
+  if (e.toString().includes('object Object')) {
+    console.log(e)
+  }
+})

package/src/index.ts

@@ -1 +1,4 @@
-export * from 'lib/index.js'
+// This package is a CLI, not a library: nothing here is part of a public API.
+// The entrypoint exists so that importing the package resolves to a module
+// instead of failing, for consumers that depend on it to get the bin.
+export default null

package/src/lib/get-api-blueprint.ts

@@ -0,0 +1,17 @@
+import { type Blueprint, createBlueprint } from '@seamapi/blueprint'
+import { getOpenapiSchema } from '@seamapi/http/connect'
+import * as seamTypes from '@seamapi/types/connect'
+
+import { getServer } from './get-server.js'
+
+export type ApiBlueprint = Blueprint
+
+export const getApiBlueprint = async (
+  useRemoteDefinitions: boolean,
+): Promise<ApiBlueprint> => {
+  const typesModule = useRemoteDefinitions
+    ? { ...seamTypes, openapi: await getOpenapiSchema(getServer()) }
+    : seamTypes
+
+  return createBlueprint(typesModule, { omitUndocumented: true })
+}

package/src/lib/get-command-blueprint-def.ts

@@ -0,0 +1,15 @@
+import type { ContextHelpers } from './types.js'
+export const getCommandBlueprintDef = (
+  cmd: string[],
+  helpers: ContextHelpers,
+) => {
+  const path = `/${cmd.join('/').replace(/-/g, '_')}`
+  const def = helpers.blueprint.routes
+    .flatMap((route) => route.endpoints)
+    .find((endpoint) => endpoint.path === path)
+  if (!def) {
+    throw new Error(`No definition for path ${path}`)
+  }
+
+  return def
+}

package/src/lib/get-config-store.ts

@@ -0,0 +1,5 @@
+import Configstore from 'configstore'
+
+export const getConfigStore = () => {
+  return new Configstore('seam-cli', {})
+}

package/src/lib/get-current-workspace-id.ts

@@ -0,0 +1,11 @@
+import { getConfigStore } from './get-config-store.js'
+import { interactForWorkspaceId } from './interact-for-workspace-id.js'
+
+export const getCurrentWorkspaceId = async (): Promise<string> => {
+  const configStore = getConfigStore()
+
+  const currentWorkspaceId = configStore.get('current_workspace_id')
+  if (typeof currentWorkspaceId === 'string') return currentWorkspaceId
+
+  return await interactForWorkspaceId()
+}

package/src/lib/get-seam.ts

@@ -0,0 +1,43 @@
+import {
+  isConsoleSessionToken,
+  isPersonalAccessToken,
+  SeamHttp,
+  SeamHttpWithoutWorkspace,
+} from '@seamapi/http/connect'
+
+import { getConfigStore } from './get-config-store.js'
+import { getServer } from './get-server.js'
+
+export const getSeam = async (): Promise<SeamHttp> => {
+  const config = getConfigStore()
+
+  const token = config.get(`${getServer()}.pat`) as string
+
+  const workspaceId = config.get('current_workspace_id') as string
+
+  const options = { endpoint: getServer() }
+
+  if (isPersonalAccessToken(token)) {
+    return SeamHttp.fromPersonalAccessToken(token, workspaceId, options)
+  }
+
+  if (isConsoleSessionToken(token)) {
+    return SeamHttp.fromConsoleSessionToken(token, workspaceId, options)
+  }
+
+  return SeamHttp.fromApiKey(token, options)
+}
+
+export const getSeamMultiWorkspace = async (): Promise<
+  SeamHttpWithoutWorkspace | SeamHttp
+> => {
+  const config = getConfigStore()
+  const token = config.get(`${getServer()}.pat`) as string
+  const options = { endpoint: getServer() }
+
+  if (isPersonalAccessToken(token)) {
+    return SeamHttpWithoutWorkspace.fromPersonalAccessToken(token, options)
+  }
+
+  return getSeam()
+}

package/src/lib/get-server.ts

@@ -0,0 +1,9 @@
+import { getConfigStore } from './get-config-store.js'
+
+export const getServer = (): string => {
+  const config = getConfigStore()
+
+  const server = config.get('server')
+
+  return typeof server === 'string' ? server : 'https://connect.getseam.com'
+}

package/src/lib/interact-for-access-code.ts

@@ -0,0 +1,25 @@
+import { getSeam } from './get-seam.js'
+import { interactForDevice } from './interact-for-device.js'
+import { interactForResource } from './interact-for-resource.js'
+
+export const interactForAccessCode = async ({
+  device_id,
+}: {
+  device_id?: string
+}) => {
+  const seam = await getSeam()
+
+  if (!device_id) {
+    device_id = await interactForDevice()
+  }
+
+  return interactForResource({
+    resourceName: 'access_code',
+    fetchResources: () => seam.accessCodes.list({ device_id }),
+    toChoice: (accessCode) => ({
+      title: accessCode.name ?? '<No Name>',
+      value: accessCode.access_code_id,
+      description: `${accessCode.type} ${accessCode.access_code_id}`,
+    }),
+  })
+}

package/src/lib/interact-for-acs-entrance.ts

@@ -0,0 +1,16 @@
+import { getSeam } from './get-seam.js'
+import { interactForResource } from './interact-for-resource.js'
+
+export const interactForAcsEntrance = async () => {
+  const seam = await getSeam()
+
+  return interactForResource({
+    resourceName: 'ACS entrance',
+    fetchResources: () => seam.acs.entrances.list(),
+    toChoice: (entrance) => ({
+      title: entrance.display_name ?? '<No Name>',
+      value: entrance.acs_entrance_id,
+      description: entrance.acs_entrance_id,
+    }),
+  })
+}

package/src/lib/interact-for-acs-system.ts

@@ -0,0 +1,17 @@
+import { getSeam } from './get-seam.js'
+import { interactForResource } from './interact-for-resource.js'
+
+export const interactForAcsSystem = async (message?: string) => {
+  const seam = await getSeam()
+
+  return interactForResource({
+    resourceName: 'ACS system',
+    fetchResources: () => seam.acs.systems.list(),
+    message,
+    toChoice: (system) => ({
+      title: `${system.name} ${system.external_type_display_name}`,
+      value: system.acs_system_id,
+      description: system.acs_system_id,
+    }),
+  })
+}

package/src/lib/interact-for-acs-user.ts

@@ -0,0 +1,21 @@
+import { getSeam } from './get-seam.js'
+import { interactForAcsSystem } from './interact-for-acs-system.js'
+import { interactForResource } from './interact-for-resource.js'
+
+export const interactForAcsUser = async () => {
+  const seam = await getSeam()
+
+  const acs_system_id = await interactForAcsSystem(
+    'What acs_system does the acs_user belong to?',
+  )
+
+  return interactForResource({
+    resourceName: 'ACS user',
+    fetchResources: () => seam.acs.users.list({ acs_system_id }),
+    toChoice: (user) => ({
+      title: `${user.display_name} ${user.email_address}`,
+      value: user.acs_user_id,
+      description: user.acs_user_id,
+    }),
+  })
+}

package/src/lib/interact-for-action-attempt-poll.ts

@@ -0,0 +1,35 @@
+import type { ActionAttemptsGetResponse } from '@seamapi/http/connect'
+import prompts from 'prompts'
+
+import { getSeam } from './get-seam.js'
+import { withLoading } from './util/with-loading.js'
+
+export const interactForActionAttemptPoll = async (
+  action_attempt: ActionAttemptsGetResponse['action_attempt'],
+) => {
+  if (action_attempt.status === 'pending') {
+    const { poll_for_action_attempt } = await prompts({
+      name: 'poll_for_action_attempt',
+      message: "Would you like to poll the action attempt until it's ready?",
+      type: 'toggle',
+      initial: true,
+      active: 'yes',
+      inactive: 'no',
+    })
+
+    if (poll_for_action_attempt) {
+      const seam = await getSeam()
+      const { action_attempt_id } = action_attempt
+
+      const updated_action_attempt = await withLoading(
+        'Polling action attempt...',
+        () =>
+          seam.actionAttempts.get(
+            { action_attempt_id },
+            { waitForActionAttempt: { pollingInterval: 240, timeout: 10_000 } },
+          ),
+      )
+      console.dir(updated_action_attempt, { depth: null })
+    }
+  }
+}

package/src/lib/interact-for-array.ts

@@ -0,0 +1,61 @@
+import prompts from 'prompts'
+
+export const interactForArray = async (
+  array: string[],
+  message: string,
+): Promise<string[]> => {
+  const updatedArray = [...array]
+
+  const displayList = () => {
+    console.log(`${message} Current list:`)
+    if (updatedArray.length > 0) {
+      updatedArray.forEach((item, index) => {
+        console.log(`${index + 1}: ${item}`)
+      })
+    } else {
+      console.log('The list is currently empty.')
+    }
+  }
+
+  let action: string
+  do {
+    displayList()
+
+    const response = await prompts({
+      type: 'select',
+      name: 'action',
+      message: 'Choose an action:',
+      choices: [
+        { title: 'Add an item', value: 'add' },
+        { title: 'Remove an item', value: 'remove' },
+        { title: 'Finish editing', value: 'done' },
+      ],
+    })
+
+    action = response.action
+
+    if (action === 'add') {
+      const { newItem } = await prompts({
+        type: 'text',
+        name: 'newItem',
+        message: 'Enter the new item:',
+      })
+      if (newItem) {
+        updatedArray.push(newItem)
+      }
+    } else if (action === 'remove') {
+      const { index } = await prompts({
+        type: 'number',
+        name: 'index',
+        message: 'Enter the index of the item to remove:',
+        validate: (value) =>
+          value > 0 && value <= updatedArray.length ? true : 'Invalid index',
+      })
+      if (index) {
+        updatedArray.splice(index - 1, 1)
+      }
+    }
+  } while (action !== 'done')
+
+  return updatedArray
+}