@seamapi/cli 0.18.1 → 0.19.0

package/src/lib/context.ts

@@ -0,0 +1,84 @@
+import type { Interactivity } from './args/parse.js'
+import type { ApiBlueprint } from './blueprint/index.js'
+import { type ConfigStore, getConfigStore } from './config/index.js'
+import {
+  getEndpointFromEnv,
+  getTokenFromEnv,
+  getWorkspaceIdFromEnv,
+} from './env.js'
+import type { SeamApi } from './http/api.js'
+import type { Output } from './output/output.js'
+
+export const defaultServer = 'https://connect.getseam.com'
+
+/** Where a resolved value came from, e.g., to refuse writes the env shadows. */
+export type ValueSource = 'env' | 'config' | 'default'
+
+/**
+ * The server, token, and workspace requests are made with.
+ *
+ * Resolved in one place so the precedence rule exists once: an environment
+ * variable wins over the stored value, and the server falls back to Seam.
+ * The source tags say where each value came from.
+ */
+export interface AuthContext {
+  server: string
+  serverSource: ValueSource
+  token: string | null
+  tokenSource: Exclude<ValueSource, 'default'> | null
+  workspaceId: string | null
+  workspaceIdSource: Exclude<ValueSource, 'default'> | null
+}
+
+export const resolveAuth = (
+  config: ConfigStore = getConfigStore(),
+): AuthContext => {
+  const envServer = getEndpointFromEnv()
+  const storedServer = config.get('server')
+  const server =
+    envServer ?? (typeof storedServer === 'string' ? storedServer : null)
+
+  const envToken = getTokenFromEnv()
+  const storedToken = readString(config.get(`${server ?? defaultServer}.pat`))
+
+  const envWorkspaceId = getWorkspaceIdFromEnv()
+  const storedWorkspaceId = readString(config.get('current_workspace_id'))
+
+  return {
+    server: server ?? defaultServer,
+    serverSource:
+      envServer != null ? 'env' : server != null ? 'config' : 'default',
+    token: envToken ?? storedToken,
+    tokenSource:
+      envToken != null ? 'env' : storedToken != null ? 'config' : null,
+    workspaceId: envWorkspaceId ?? storedWorkspaceId,
+    workspaceIdSource:
+      envWorkspaceId != null
+        ? 'env'
+        : storedWorkspaceId != null
+          ? 'config'
+          : null,
+  }
+}
+
+/**
+ * Everything a command runs with: the stores and auth it reads, the API
+ * shape it acts on, and how it may interact with the user.
+ */
+export interface CliContext {
+  config: ConfigStore
+  auth: AuthContext
+  output: Output
+  blueprint: ApiBlueprint
+  interactivity: Interactivity
+  /** The Seam API, constructed on first use and shared for the run. */
+  api: () => Promise<SeamApi>
+}
+
+const readString = (value: unknown): string | null => {
+  if (typeof value !== 'string') return null
+
+  const trimmedValue = value.trim()
+
+  return trimmedValue === '' ? null : trimmedValue
+}

package/src/lib/env.ts

@@ -16,7 +16,7 @@ export const workspaceIdEnvVar = 'SEAM_CLI_WORKSPACE_ID'
 export const endpointEnvVar = 'SEAM_CLI_ENDPOINT'
 
 /** Every variable read here is declared on `ProcessEnv` in `env.d.ts`. */
-type SeamCliEnvVar =
+type CliEnvVar =
   typeof endpointEnvVar | typeof tokenEnvVar | typeof workspaceIdEnvVar
 
 export const getTokenFromEnv = (): string | null => readEnvVar(tokenEnvVar)
@@ -52,7 +52,14 @@ export const assertEnvVarUnset = (
   )
 }
 
-const readEnvVar = (envVar: SeamCliEnvVar): string | null => {
+/**
+ * Whether the CLI runs inside a hosted web terminal, where it cannot open
+ * anything in a browser of its own.
+ */
+export const isInsideWebBrowser = (): boolean =>
+  process.env['INSIDE_WEB_BROWSER'] === '1'
+
+const readEnvVar = (envVar: CliEnvVar): string | null => {
   const value = process.env[envVar]
 
   if (value == null) return null

package/src/lib/errors.ts

@@ -0,0 +1,67 @@
+import chalk from 'chalk'
+
+import { EnvVarOverrideError } from './env.js'
+import type { Output } from './output/output.js'
+
+/**
+ * Thrown when the CLI needs input it cannot prompt for.
+ */
+export class NonInteractiveError extends Error {
+  override name = 'NonInteractiveError'
+}
+
+/**
+ * Thrown when the user dismisses a prompt with ctrl-c or escape instead of
+ * answering it.
+ */
+export class PromptCancelledError extends Error {
+  constructor() {
+    super('Cancelled')
+  }
+}
+
+/**
+ * Thrown when the arguments do not name something the CLI can run.
+ */
+export class UsageError extends Error {
+  override name = 'UsageError'
+
+  /** What to run instead, reported after the message. */
+  readonly hint: string
+
+  constructor(message: string, { hint = '' }: { hint?: string } = {}) {
+    super(message)
+    this.hint = hint
+  }
+}
+
+/**
+ * Report a failure and set the exit code: usage mistakes read as one line
+ * with a hint, environment overrides without a stack trace, and anything
+ * else as an unexpected CLI error.
+ */
+export const reportErrorAndExit = (e: unknown, output: Output): void => {
+  process.exitCode = 1
+
+  if (e instanceof UsageError) {
+    output.error(chalk.red(e.message))
+    if (e.hint !== '') output.error(e.hint)
+    return
+  }
+
+  if (e instanceof NonInteractiveError || e instanceof EnvVarOverrideError) {
+    output.error(chalk.red(e.message))
+    return
+  }
+
+  // Dismissing a prompt is the user stopping the CLI, not the CLI failing:
+  // note it quietly, without the alarm of an error.
+  if (e instanceof PromptCancelledError) {
+    output.error(chalk.gray(e.message))
+    return
+  }
+
+  const error = e instanceof Error ? e : new Error(String(e))
+  output.error(chalk.red(`CLI Error: ${error.message}`))
+  if (error.stack != null) output.error(chalk.gray(error.stack))
+}

package/src/lib/http/api.ts

@@ -0,0 +1,61 @@
+import { type SeamHttp, SeamHttpRequest } from '@seamapi/http/connect'
+
+import type { AuthContext } from 'lib/context.js'
+
+import { getSeam } from './client.js'
+
+export interface ApiRequestOptions {
+  path: string
+  params: Record<string, unknown>
+  /** Response key documented for the endpoint, e.g., `devices`. */
+  responseKey?: string | null | undefined
+}
+
+/**
+ * A prepared call to the Seam API: inspectable before it is sent, e.g., to
+ * report the URL, then sent with {@link SeamApiRequest.fetchResponse}.
+ *
+ * The real implementation is the SDK's own `SeamHttpRequest`; sending one
+ * rejects with a `SeamHttpApiError` when the API reports an error.
+ */
+export interface SeamApiRequest {
+  readonly url: URL
+  readonly method: string
+  readonly body: unknown
+  /** Send the request and return the full response body. */
+  fetchResponse: () => Promise<unknown>
+}
+
+/**
+ * How the blueprint-driven CLI reaches the Seam API: prepare a request for
+ * an endpoint path. Tests fake at this port with `createMemorySeamApi()` —
+ * the in-process mirror of the e2e suite's HTTP server.
+ */
+export interface SeamApi {
+  createRequest: (options: ApiRequestOptions) => SeamApiRequest
+}
+
+/** The only place `SeamHttp` appears for raw requests. */
+export class HttpSeamApi implements SeamApi {
+  constructor(private readonly seam: SeamHttp) {}
+
+  createRequest = ({
+    path,
+    params,
+    responseKey,
+  }: ApiRequestOptions): SeamApiRequest =>
+    new SeamHttpRequest<Record<string, unknown>, string | undefined>(
+      this.seam,
+      {
+        pathname: path,
+        method: 'POST',
+        body: params,
+        responseKey: responseKey ?? undefined,
+      },
+    )
+}
+
+export const createSeamApi = async (auth?: AuthContext): Promise<SeamApi> => {
+  const seam = await getSeam(auth)
+  return new HttpSeamApi(seam)
+}

package/src/lib/{get-seam.ts → http/client.ts}

@@ -5,19 +5,20 @@ import {
   SeamHttpWithoutWorkspace,
 } from '@seamapi/http/connect'
 
-import { tokenEnvVar, workspaceIdEnvVar } from './env.js'
-import { getToken, getWorkspaceId } from './get-credentials.js'
-import { getServer } from './get-server.js'
+import { type AuthContext, resolveAuth } from 'lib/context.js'
+import { tokenEnvVar, workspaceIdEnvVar } from 'lib/env.js'
 
-export const getSeam = async (): Promise<SeamHttp> => {
-  const token = getRequiredToken()
+export const getSeam = async (
+  auth: AuthContext = resolveAuth(),
+): Promise<SeamHttp> => {
+  const token = getRequiredToken(auth)
 
-  const options = { endpoint: getServer() }
+  const options = { endpoint: auth.server }
 
   if (isPersonalAccessToken(token)) {
     return SeamHttp.fromPersonalAccessToken(
       token,
-      getRequiredWorkspaceId(),
+      getRequiredWorkspaceId(auth),
       options,
     )
   }
@@ -25,7 +26,7 @@ export const getSeam = async (): Promise<SeamHttp> => {
   if (isConsoleSessionToken(token)) {
     return SeamHttp.fromConsoleSessionToken(
       token,
-      getRequiredWorkspaceId(),
+      getRequiredWorkspaceId(auth),
       options,
     )
   }
@@ -33,21 +34,21 @@ export const getSeam = async (): Promise<SeamHttp> => {
   return SeamHttp.fromApiKey(token, options)
 }
 
-export const getSeamMultiWorkspace = async (): Promise<
-  SeamHttpWithoutWorkspace | SeamHttp
-> => {
-  const token = getRequiredToken()
-  const options = { endpoint: getServer() }
+export const getSeamMultiWorkspace = async (
+  auth: AuthContext = resolveAuth(),
+): Promise<SeamHttpWithoutWorkspace | SeamHttp> => {
+  const token = getRequiredToken(auth)
+  const options = { endpoint: auth.server }
 
   if (isPersonalAccessToken(token)) {
     return SeamHttpWithoutWorkspace.fromPersonalAccessToken(token, options)
   }
 
-  return await getSeam()
+  return await getSeam(auth)
 }
 
-const getRequiredToken = (): string => {
-  const token = getToken()
+const getRequiredToken = (auth: AuthContext): string => {
+  const { token } = auth
 
   if (token == null) {
     throw new Error(
@@ -58,8 +59,8 @@ const getRequiredToken = (): string => {
   return token
 }
 
-const getRequiredWorkspaceId = (): string => {
-  const workspaceId = getWorkspaceId()
+const getRequiredWorkspaceId = (auth: AuthContext): string => {
+  const { workspaceId } = auth
 
   if (workspaceId == null) {
     throw new Error(

package/src/lib/http/follow-ups.ts

@@ -0,0 +1,42 @@
+import type { CliContext } from 'lib/context.js'
+import { isInsideWebBrowser } from 'lib/env.js'
+import { interactForActionAttemptPoll } from 'lib/interactions/index.js'
+import { promptConfirm } from 'lib/prompt.js'
+
+/**
+ * Follow-ups a response may call for: opening a connect webview in the
+ * browser, and offering to poll a pending action attempt.
+ */
+export const runResponseFollowUps = async (
+  data: any,
+  ctx: CliContext,
+): Promise<void> => {
+  const isNonInteractive = ctx.interactivity === 'non-interactive'
+
+  if (data?.connect_webview) {
+    await handleConnectWebview(data.connect_webview, isNonInteractive)
+  }
+
+  if (data?.action_attempt && !isNonInteractive) {
+    await interactForActionAttemptPoll(data.action_attempt)
+  }
+}
+
+const handleConnectWebview = async (
+  connectWebview: any,
+  isNonInteractive: boolean,
+): Promise<void> => {
+  const url = connectWebview.url
+
+  if (!isNonInteractive && !isInsideWebBrowser()) {
+    const action = await promptConfirm({
+      message: 'Would you like to open the webview in your browser?',
+      initialValue: false,
+    })
+
+    if (action) {
+      const { default: open } = await import('open')
+      await open(url)
+    }
+  }
+}

package/src/lib/http/memory-seam-api.ts

@@ -0,0 +1,57 @@
+import {
+  SeamHttpApiError,
+  SeamHttpInvalidInputError,
+} from '@seamapi/http/connect'
+
+import type { ApiRequestOptions, SeamApi, SeamApiRequest } from './api.js'
+
+export interface MemorySeamApiResponse {
+  status: number
+  data: unknown
+}
+
+/**
+ * A real {@link SeamApi} answering from a routes table and recording every
+ * request, for tests: the in-process mirror of the e2e suite's HTTP server.
+ * Error statuses reject with the SDK's own error classes, exactly as the
+ * real transport does.
+ */
+export class MemorySeamApi implements SeamApi {
+  /** Every request sent, in order — assert on the outbound messages. */
+  readonly requests: Array<{ path: string; params: Record<string, unknown> }> =
+    []
+
+  constructor(private readonly routes: Record<string, MemorySeamApiResponse>) {}
+
+  createRequest = ({ path, params }: ApiRequestOptions): SeamApiRequest => ({
+    url: new URL(`https://memory.seam.example${path}`),
+    method: 'POST',
+    body: params,
+    fetchResponse: async () => {
+      this.requests.push({ path, params })
+
+      const route = this.routes[path] ?? {
+        status: 404,
+        data: { error: { type: 'not_found', message: 'Not Found' } },
+      }
+
+      if (route.status >= 400) {
+        throw toSeamHttpError(route)
+      }
+      return route.data
+    },
+  })
+}
+
+const toSeamHttpError = (route: MemorySeamApiResponse): SeamHttpApiError => {
+  const error = (route.data as { error: { type: string; message: string } })
+    .error
+  if (error.type === 'invalid_input') {
+    return new SeamHttpInvalidInputError(error, route.status, 'request_memory')
+  }
+  return new SeamHttpApiError(error, route.status, 'request_memory')
+}
+
+export const createMemorySeamApi = (
+  routes: Record<string, MemorySeamApiResponse>,
+): MemorySeamApi => new MemorySeamApi(routes)

package/src/lib/http/request.ts

@@ -0,0 +1,69 @@
+import {
+  isSeamHttpApiError,
+  type SeamHttpApiError,
+} from '@seamapi/http/connect'
+import chalk from 'chalk'
+
+import type { Output } from 'lib/output/output.js'
+import { selectResponsePayload } from 'lib/output/select-response-payload.js'
+import { withLoading } from 'lib/output/with-loading.js'
+
+import type { SeamApi } from './api.js'
+
+export interface RequestSeamApiOptions {
+  path: string
+  params: Record<string, any>
+  /** Response key for the endpoint, used to trim the reported payload. */
+  responseKey?: string | null | undefined
+}
+
+export interface RequestSeamApiDependencies {
+  api: SeamApi
+  output: Output
+}
+
+/**
+ * Make a request and report the result: the request URL and params go to
+ * stderr, the trimmed payload to stdout. An API error reports its status
+ * and payload and sets the exit code. Returns the response body, or `null`
+ * when the API reported an error.
+ */
+export const requestSeamApi = async (
+  options: RequestSeamApiOptions,
+  { api, output }: RequestSeamApiDependencies,
+): Promise<unknown> => {
+  const request = api.createRequest(options)
+
+  output.info(`\n${chalk.green(request.url.toString())}`)
+  output.info(`Request Params:`)
+  output.info(formatParams(options.params))
+
+  let body: unknown
+  try {
+    body = await withLoading('Making request...', async () => {
+      return await request.fetchResponse()
+    })
+  } catch (error) {
+    if (!isSeamHttpApiError(error)) throw error
+
+    output.warn(chalk.red(`[${error.statusCode}]`))
+    process.exitCode = 1
+    output.data({ error: toErrorPayload(error) })
+    return null
+  }
+
+  output.data(selectResponsePayload(body, { responseKey: options.responseKey }))
+
+  return body
+}
+
+const toErrorPayload = (
+  error: SeamHttpApiError,
+): { type: string; message: string; data?: unknown } => ({
+  type: error.code,
+  message: error.message,
+  ...(error.data === undefined ? {} : { data: error.data }),
+})
+
+const formatParams = (params: Record<string, any>): string =>
+  JSON.stringify(params, null, 2)

package/src/lib/{interact-for-access-code.ts → interactions/access-code.ts}

@@ -1,6 +1,7 @@
-import { getSeam } from './get-seam.js'
-import { interactForDevice } from './interact-for-device.js'
-import { interactForResource } from './interact-for-resource.js'
+import { getSeam } from 'lib/http/client.js'
+
+import { interactForDevice } from './device.js'
+import { interactForResource } from './resource.js'
 
 export const interactForAccessCode = async ({
   // The key is a Seam API parameter name: callers pass the blueprint params

package/src/lib/{interact-for-acs-entrance.ts → interactions/acs-entrance.ts}

@@ -1,5 +1,6 @@
-import { getSeam } from './get-seam.js'
-import { interactForResource } from './interact-for-resource.js'
+import { getSeam } from 'lib/http/client.js'
+
+import { interactForResource } from './resource.js'
 
 export const interactForAcsEntrance = async () => {
   const seam = await getSeam()

package/src/lib/{interact-for-acs-system.ts → interactions/acs-system.ts}

@@ -1,5 +1,6 @@
-import { getSeam } from './get-seam.js'
-import { interactForResource } from './interact-for-resource.js'
+import { getSeam } from 'lib/http/client.js'
+
+import { interactForResource } from './resource.js'
 
 export const interactForAcsSystem = async (message?: string) => {
   const seam = await getSeam()

package/src/lib/{interact-for-acs-user.ts → interactions/acs-user.ts}

@@ -1,6 +1,7 @@
-import { getSeam } from './get-seam.js'
-import { interactForAcsSystem } from './interact-for-acs-system.js'
-import { interactForResource } from './interact-for-resource.js'
+import { getSeam } from 'lib/http/client.js'
+
+import { interactForAcsSystem } from './acs-system.js'
+import { interactForResource } from './resource.js'
 
 export const interactForAcsUser = async () => {
   const seam = await getSeam()

package/src/lib/{interact-for-action-attempt-poll.ts → interactions/action-attempt-poll.ts}

@@ -1,9 +1,9 @@
 import type { ActionAttemptsGetResponse } from '@seamapi/http/connect'
 
-import { getSeam } from './get-seam.js'
-import { getOutput } from './output/get-output.js'
-import { promptConfirm } from './util/prompt.js'
-import { withLoading } from './util/with-loading.js'
+import { getSeam } from 'lib/http/client.js'
+import { getOutput } from 'lib/output/get-output.js'
+import { withLoading } from 'lib/output/with-loading.js'
+import { promptConfirm } from 'lib/prompt.js'
 
 export const interactForActionAttemptPoll = async (
   actionAttempt: ActionAttemptsGetResponse['action_attempt'],

package/src/lib/{interact-for-array.ts → interactions/array.ts}

@@ -1,11 +1,11 @@
-import { getOutput } from './output/get-output.js'
+import { PromptCancelledError } from 'lib/errors.js'
+import { getOutput } from 'lib/output/get-output.js'
 import {
-  PromptCancelledError,
   promptNumber,
   promptSelect,
   promptText,
   withBackHint,
-} from './util/prompt.js'
+} from 'lib/prompt.js'
 
 export const interactForArray = async (
   array: string[],