@seamapi/http 2.1.0 → 2.3.0

package/src/lib/options.ts

@@ -0,0 +1,242 @@
+import type { Client, ClientOptions } from './client.js'
+import {
+  isSeamHttpRequestOption,
+  type SeamHttpRequestOptions,
+} from './request-options.js'
+
+export type { SeamHttpRequestOptions } from './request-options.js'
+
+export type SeamHttpWithoutWorkspaceOptions =
+  | SeamHttpWithoutWorkspaceOptionsFromEnv
+  | SeamHttpWithoutWorkspaceOptionsWithClient
+  | SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken
+  | SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken
+
+export type SeamHttpOptions =
+  | SeamHttpOptionsFromEnv
+  | SeamHttpOptionsWithClient
+  | SeamHttpOptionsWithApiKey
+  | SeamHttpOptionsWithClientSessionToken
+  | SeamHttpOptionsWithConsoleSessionToken
+  | SeamHttpOptionsWithPersonalAccessToken
+
+interface SeamHttpCommonOptions extends ClientOptions, SeamHttpRequestOptions {
+  endpoint?: string
+}
+
+export interface SeamHttpFromPublishableKeyOptions extends SeamHttpCommonOptions {}
+
+export interface SeamHttpOptionsFromEnv extends SeamHttpCommonOptions {}
+
+export interface SeamHttpWithoutWorkspaceOptionsFromEnv extends SeamHttpCommonOptions {}
+
+export interface SeamHttpWithoutWorkspaceOptionsWithClient extends SeamHttpCommonOptions {
+  client: Client
+}
+
+export const isSeamHttpWithoutWorkspaceOptionsWithClient = (
+  options: SeamHttpOptions,
+): options is SeamHttpWithoutWorkspaceOptionsWithClient =>
+  isSeamHttpOptionsWithClient(options)
+
+export interface SeamHttpOptionsWithClient extends SeamHttpRequestOptions {
+  client: Client
+}
+
+export const isSeamHttpOptionsWithClient = (
+  options: SeamHttpOptions,
+): options is SeamHttpOptionsWithClient => {
+  if (!('client' in options)) return false
+  if (options.client == null) return false
+
+  const keys = Object.keys(options).filter((k) => k !== 'client')
+  if (keys.filter((k) => !isSeamHttpRequestOption(k)).length > 0) {
+    throw new SeamHttpInvalidOptionsError(
+      `The client option cannot be used with any other option, but received: ${keys.join(
+        ', ',
+      )}`,
+    )
+  }
+
+  return true
+}
+
+export interface SeamHttpOptionsWithApiKey extends SeamHttpCommonOptions {
+  apiKey: string
+}
+
+export const isSeamHttpOptionsWithApiKey = (
+  options: SeamHttpOptions,
+): options is SeamHttpOptionsWithApiKey => {
+  if (!('apiKey' in options)) return false
+  if (options.apiKey == null) return false
+
+  if ('clientSessionToken' in options && options.clientSessionToken != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The clientSessionToken option cannot be used with the apiKey option',
+    )
+  }
+
+  if ('consoleSessionToken' in options && options.consoleSessionToken != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The consoleSessionToken option cannot be used with the apiKey option',
+    )
+  }
+
+  if ('personalAccessToken' in options && options.personalAccessToken != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The personalAccessToken option cannot be used with the apiKey option',
+    )
+  }
+
+  return true
+}
+
+export interface SeamHttpOptionsWithClientSessionToken extends SeamHttpCommonOptions {
+  clientSessionToken: string
+}
+
+export const isSeamHttpOptionsWithClientSessionToken = (
+  options: SeamHttpOptions,
+): options is SeamHttpOptionsWithClientSessionToken => {
+  if (!('clientSessionToken' in options)) return false
+  if (options.clientSessionToken == null) return false
+
+  if ('apiKey' in options && options.apiKey != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The apiKey option cannot be used with the clientSessionToken option',
+    )
+  }
+
+  if ('consoleSessionToken' in options && options.consoleSessionToken != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The consoleSessionToken option cannot be used with the clientSessionToken option',
+    )
+  }
+
+  if ('personalAccessToken' in options && options.personalAccessToken != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The personalAccessToken option cannot be used with the clientSessionToken option',
+    )
+  }
+
+  return true
+}
+
+export interface SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken extends SeamHttpCommonOptions {
+  consoleSessionToken: string
+}
+
+export const isSeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken = (
+  options: SeamHttpOptions,
+): options is SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken => {
+  if (!('consoleSessionToken' in options)) return false
+  if (options.consoleSessionToken == null) return false
+
+  if ('apiKey' in options && options.apiKey != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The apiKey option cannot be used with the consoleSessionToken option',
+    )
+  }
+
+  if ('clientSessionToken' in options && options.clientSessionToken != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The clientSessionToken option cannot be used with the consoleSessionToken option',
+    )
+  }
+
+  if ('personalAccessToken' in options && options.personalAccessToken != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The personalAccessToken option cannot be used with the consoleSessionToken option',
+    )
+  }
+
+  return true
+}
+
+export interface SeamHttpOptionsWithConsoleSessionToken extends SeamHttpCommonOptions {
+  consoleSessionToken: string
+  workspaceId: string
+}
+
+export const isSeamHttpOptionsWithConsoleSessionToken = (
+  options: SeamHttpOptions,
+): options is SeamHttpOptionsWithConsoleSessionToken => {
+  if (!isSeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken(options)) {
+    return false
+  }
+
+  if (!('workspaceId' in options) || options.workspaceId == null) {
+    throw new SeamHttpInvalidOptionsError(
+      'Must pass a workspaceId when using a consoleSessionToken',
+    )
+  }
+
+  return true
+}
+
+export interface SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken extends SeamHttpCommonOptions {
+  personalAccessToken: string
+}
+
+export const isSeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken = (
+  options: SeamHttpOptions,
+): options is SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken => {
+  if (!('personalAccessToken' in options)) return false
+  if (options.personalAccessToken == null) return false
+
+  if ('apiKey' in options && options.apiKey != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The apiKey option cannot be used with the personalAccessToken option',
+    )
+  }
+
+  if ('clientSessionToken' in options && options.clientSessionToken != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The clientSessionToken option cannot be used with the personalAccessToken option',
+    )
+  }
+
+  if ('consoleSessionToken' in options && options.consoleSessionToken != null) {
+    throw new SeamHttpInvalidOptionsError(
+      'The consoleSessionToken option cannot be used with the personalAccessToken option',
+    )
+  }
+
+  return true
+}
+
+export interface SeamHttpOptionsWithPersonalAccessToken extends SeamHttpCommonOptions {
+  personalAccessToken: string
+  workspaceId: string
+}
+
+export const isSeamHttpOptionsWithPersonalAccessToken = (
+  options: SeamHttpOptions,
+): options is SeamHttpOptionsWithPersonalAccessToken => {
+  if (!isSeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken(options)) {
+    return false
+  }
+
+  if (!('workspaceId' in options) || options.workspaceId == null) {
+    throw new SeamHttpInvalidOptionsError(
+      'Must pass a workspaceId when using a personalAccessToken',
+    )
+  }
+
+  return true
+}
+
+export class SeamHttpInvalidOptionsError extends Error {
+  constructor(message: string) {
+    super(`SeamHttp received invalid options: ${message}`)
+    this.name = this.constructor.name
+  }
+}
+
+export class SeamHttpWithoutWorkspaceInvalidOptionsError extends Error {
+  constructor(message: string) {
+    super(`SeamHttpWithoutWorkspace received invalid options: ${message}`)
+    this.name = this.constructor.name
+  }
+}

package/src/lib/parse-options.ts

@@ -0,0 +1,182 @@
+import { seamApiLtsVersion } from 'lib/lts-version.js'
+import version from 'lib/version.js'
+
+import { getAuthHeaders } from './auth.js'
+import { type Client, type ClientOptions, defaultTimeout } from './client.js'
+import {
+  isSeamHttpOptionsWithClient,
+  isSeamHttpOptionsWithClientSessionToken,
+  isSeamHttpWithoutWorkspaceOptionsWithClient,
+  SeamHttpInvalidOptionsError,
+  type SeamHttpOptions,
+  type SeamHttpRequestOptions,
+  type SeamHttpWithoutWorkspaceOptions,
+} from './options.js'
+import { isSeamHttpRequestOption } from './request-options.js'
+
+export const defaultEndpoint = 'https://connect.getseam.com'
+
+export const sdkHeaders = {
+  'seam-sdk-name': 'seamapi/javascript-http',
+  'seam-sdk-version': version,
+  'seam-lts-version': seamApiLtsVersion,
+}
+
+export type Options =
+  | SeamHttpWithoutWorkspaceOptions
+  | (SeamHttpOptions & { publishableKey?: string })
+
+type ParsedOptions = Required<
+  (ClientOptions | { client: Client }) & SeamHttpRequestOptions
+>
+
+export const parseOptions = (
+  apiKeyOrOptions: string | Options,
+): ParsedOptions => {
+  const options = getNormalizedOptions(apiKeyOrOptions)
+
+  if (isSeamHttpOptionsWithClient(options)) return options
+  if (isSeamHttpWithoutWorkspaceOptionsWithClient(options)) return options
+
+  return {
+    ...options,
+    timeout: options.timeout ?? defaultTimeout,
+    axiosOptions: {
+      baseURL: options.endpoint ?? getEndpointFromEnv() ?? defaultEndpoint,
+      withCredentials: isSeamHttpOptionsWithClientSessionToken(options),
+      ...options.axiosOptions,
+      headers: {
+        ...getAuthHeaders(options),
+        ...options.axiosOptions?.headers,
+        ...sdkHeaders,
+      },
+    },
+    axiosRetryOptions: {
+      ...options.axiosRetryOptions,
+    },
+  }
+}
+
+const getNormalizedOptions = (
+  apiKeyOrOptions: string | Options,
+): SeamHttpOptions & Required<SeamHttpRequestOptions> => {
+  const options =
+    typeof apiKeyOrOptions === 'string'
+      ? { apiKey: apiKeyOrOptions }
+      : apiKeyOrOptions
+
+  const requestOptions = {
+    waitForActionAttempt: options.waitForActionAttempt ?? true,
+  }
+
+  if (isSeamHttpOptionsWithClient(options)) {
+    return {
+      ...options,
+      ...requestOptions,
+    }
+  }
+
+  const apiKey =
+    'apiKey' in options ? options.apiKey : getApiKeyFromEnv(options)
+
+  const personalAccessToken =
+    'personalAccessToken' in options
+      ? options.personalAccessToken
+      : getPersonalAccessTokenFromEnv(options)
+
+  const workspaceId =
+    'workspaceId' in options ? options.workspaceId : getWorkspaceIdFromEnv()
+
+  if (
+    apiKey != null &&
+    personalAccessToken != null &&
+    !('apiKey' in options) &&
+    !('personalAccessToken' in options)
+  ) {
+    throw new SeamHttpInvalidOptionsError(
+      'Both SEAM_API_KEY and SEAM_PERSONAL_ACCESS_TOKEN environment variables are defined. Please use only one authentication method.',
+    )
+  }
+
+  return {
+    ...options,
+    ...(apiKey != null ? { apiKey } : {}),
+    ...(workspaceId != null ? { workspaceId } : {}),
+    ...(personalAccessToken != null ? { personalAccessToken } : {}),
+    ...requestOptions,
+  }
+}
+
+const getApiKeyFromEnv = (
+  options: SeamHttpOptions,
+): string | null | undefined => {
+  if ('clientSessionToken' in options && options.clientSessionToken != null) {
+    return null
+  }
+  if ('consoleSessionToken' in options && options.consoleSessionToken != null) {
+    return null
+  }
+  if ('personalAccessToken' in options && options.personalAccessToken != null) {
+    return null
+  }
+  return globalThis.process?.env?.SEAM_API_KEY
+}
+
+const getPersonalAccessTokenFromEnv = (
+  options: SeamHttpOptions,
+): string | null | undefined => {
+  if ('apiKey' in options && options.apiKey != null) {
+    return null
+  }
+  if ('clientSessionToken' in options && options.clientSessionToken != null) {
+    return null
+  }
+  if ('consoleSessionToken' in options && options.consoleSessionToken != null) {
+    return null
+  }
+  return globalThis.process?.env?.SEAM_PERSONAL_ACCESS_TOKEN
+}
+
+const getWorkspaceIdFromEnv = (): string | null | undefined => {
+  return globalThis.process?.env?.SEAM_WORKSPACE_ID
+}
+
+const getEndpointFromEnv = (): string | null | undefined => {
+  if (globalThis.process?.env?.SEAM_API_URL != null) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Using the SEAM_API_URL environment variable is deprecated. Support will be remove in a later major version. Use SEAM_ENDPOINT instead.',
+    )
+  }
+
+  if (
+    globalThis.process?.env?.SEAM_API_URL != null &&
+    globalThis.process?.env?.SEAM_ENDPOINT != null
+  ) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'Detected both the SEAM_API_URL and SEAM_ENDPOINT environment variables. Using SEAM_ENDPOINT.',
+    )
+  }
+
+  return (
+    globalThis.process?.env?.SEAM_ENDPOINT ??
+    globalThis.process?.env?.SEAM_API_URL
+  )
+}
+
+export const limitToSeamHttpRequestOptions = (
+  options: Required<SeamHttpRequestOptions>,
+): Required<SeamHttpRequestOptions> => {
+  return Object.keys(options)
+    .filter(isSeamHttpRequestOption)
+    .reduce(
+      (obj, key) => ({
+        ...obj,
+        [key]: options[key],
+      }),
+      {},
+    ) as Required<SeamHttpRequestOptions>
+}
+
+export { isSeamHttpRequestOption } from './request-options.js'

package/src/lib/request-options.ts

@@ -0,0 +1,14 @@
+import type { ResolveActionAttemptOptions } from './resolve-action-attempt.js'
+
+export interface SeamHttpRequestOptions {
+  waitForActionAttempt?: boolean | ResolveActionAttemptOptions
+}
+
+export const isSeamHttpRequestOption = (
+  key: string,
+): key is keyof SeamHttpRequestOptions => {
+  const keys: Record<keyof SeamHttpRequestOptions, true> = {
+    waitForActionAttempt: true,
+  }
+  return Object.keys(keys).includes(key)
+}

package/src/lib/resolve-action-attempt.ts

@@ -0,0 +1,129 @@
+import type { ActionAttempt } from './resources/action-attempt.js'
+
+export interface ActionAttemptsClient {
+  get(parameters: { action_attempt_id: string }): PromiseLike<ActionAttempt>
+}
+
+export interface ResolveActionAttemptOptions {
+  timeout?: number
+  pollingInterval?: number
+}
+
+export const resolveActionAttempt = async <T extends ActionAttempt>(
+  actionAttempt: T,
+  actionAttempts: ActionAttemptsClient,
+  { timeout = 10_000, pollingInterval = 1_000 }: ResolveActionAttemptOptions,
+): Promise<SucceededActionAttempt<T>> => {
+  let timeoutRef
+  const timeoutPromise = new Promise<SucceededActionAttempt<T>>(
+    (_resolve, reject) => {
+      timeoutRef = globalThis.setTimeout(() => {
+        reject(new SeamActionAttemptTimeoutError<T>(actionAttempt, timeout))
+      }, timeout)
+    },
+  )
+
+  try {
+    return await Promise.race([
+      pollActionAttempt<T>(actionAttempt, actionAttempts, { pollingInterval }),
+      timeoutPromise,
+    ])
+  } finally {
+    if (timeoutRef != null) globalThis.clearTimeout(timeoutRef)
+  }
+}
+
+const pollActionAttempt = async <T extends ActionAttempt>(
+  actionAttempt: T,
+  actionAttempts: ActionAttemptsClient,
+  options: Pick<ResolveActionAttemptOptions, 'pollingInterval'>,
+): Promise<SucceededActionAttempt<T>> => {
+  if (isSuccessfulActionAttempt(actionAttempt)) {
+    return actionAttempt
+  }
+
+  if (isFailedActionAttempt(actionAttempt)) {
+    throw new SeamActionAttemptFailedError(actionAttempt)
+  }
+
+  await new Promise((resolve) => setTimeout(resolve, options.pollingInterval))
+
+  const nextActionAttempt = await actionAttempts.get({
+    action_attempt_id: actionAttempt.action_attempt_id,
+  })
+
+  return await pollActionAttempt(
+    nextActionAttempt as unknown as T,
+    actionAttempts,
+    options,
+  )
+}
+
+export const isSeamActionAttemptError = <T extends ActionAttempt>(
+  error: unknown,
+): error is SeamActionAttemptError<T> => {
+  return error instanceof SeamActionAttemptError
+}
+
+export class SeamActionAttemptError<T extends ActionAttempt> extends Error {
+  actionAttempt: T
+
+  constructor(message: string, actionAttempt: T) {
+    super(message)
+    this.name = this.constructor.name
+    this.actionAttempt = actionAttempt
+  }
+}
+
+export const isSeamActionAttemptFailedError = <T extends ActionAttempt>(
+  error: unknown,
+): error is SeamActionAttemptFailedError<T> => {
+  return error instanceof SeamActionAttemptFailedError
+}
+
+export class SeamActionAttemptFailedError<
+  T extends ActionAttempt,
+> extends SeamActionAttemptError<T> {
+  code: string
+
+  constructor(actionAttempt: FailedActionAttempt<T>) {
+    super(actionAttempt.error.message, actionAttempt)
+    this.name = this.constructor.name
+    this.code = actionAttempt.error.type
+  }
+}
+
+export const isSeamActionAttemptTimeoutError = <T extends ActionAttempt>(
+  error: unknown,
+): error is SeamActionAttemptTimeoutError<T> => {
+  return error instanceof SeamActionAttemptTimeoutError
+}
+
+export class SeamActionAttemptTimeoutError<
+  T extends ActionAttempt,
+> extends SeamActionAttemptError<T> {
+  constructor(actionAttempt: T, timeout: number) {
+    super(
+      `Timed out waiting for action action attempt after ${timeout}ms`,
+      actionAttempt,
+    )
+    this.name = this.constructor.name
+  }
+}
+
+const isSuccessfulActionAttempt = <T extends ActionAttempt>(
+  actionAttempt: T,
+): actionAttempt is SucceededActionAttempt<T> =>
+  actionAttempt.status === 'success'
+
+const isFailedActionAttempt = <T extends ActionAttempt>(
+  actionAttempt: T,
+): actionAttempt is FailedActionAttempt<T> => actionAttempt.status === 'error'
+
+export type SucceededActionAttempt<T extends ActionAttempt> = T & {
+  status: 'success'
+}
+
+export type FailedActionAttempt<T extends ActionAttempt> = T & {
+  status: 'error'
+}