@seamapi/http 0.0.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamapi/http",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "description": "JavaScript HTTP client for the Seam API written in TypeScript.",
   "type": "module",
   "main": "index.js",
@@ -62,6 +62,7 @@
     "postversion": "git push --follow-tags",
     "example": "tsx examples",
     "example:inspect": "tsx --inspect examples",
+    "generate": "tsx generate-routes.ts",
     "format": "eslint --ignore-path .gitignore --fix .",
     "preformat": "prettier --write --ignore-path .gitignore .",
     "report": "c8 report"
@@ -83,13 +84,17 @@
     }
   },
   "dependencies": {
-    "axios": "^1.5.0"
+    "axios": "^1.5.0",
+    "axios-retry": "^3.8.0"
   },
   "devDependencies": {
-    "@seamapi/types": "^1.14.0",
+    "@seamapi/fake-seam-connect": "^1.21.0",
+    "@seamapi/types": "^1.24.0",
+    "@types/eslint": "^8.44.2",
     "@types/node": "^18.11.18",
     "ava": "^5.0.1",
     "c8": "^8.0.0",
+    "change-case": "^5.0.2",
     "concurrently": "^8.2.1",
     "del-cli": "^5.0.0",
     "eslint": "^8.9.0",
@@ -99,6 +104,7 @@
     "eslint-plugin-simple-import-sort": "^10.0.0",
     "eslint-plugin-unused-imports": "^3.0.0",
     "landlubber": "^1.0.0",
+    "node-fetch": "^3.3.2",
     "prettier": "^3.0.0",
     "tsc-alias": "^1.8.2",
     "tsup": "^7.2.0",

package/src/lib/params-serializer.ts

@@ -0,0 +1,55 @@
+import type { CustomParamsSerializer } from 'axios'
+
+export const paramsSerializer: CustomParamsSerializer = (params) => {
+  const searchParams = new URLSearchParams()
+
+  for (const [name, value] of Object.entries(params)) {
+    if (value == null) continue
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) searchParams.set(name, '')
+      if (value.length === 1 && value[0] === '') {
+        throw new UnserializableParamError(
+          name,
+          `is a single element array containing the empty string which is unsupported because it serializes to the empty array`,
+        )
+      }
+      for (const v of value) {
+        throwIfUnserializable(name, v)
+        searchParams.append(name, v)
+      }
+      continue
+    }
+
+    throwIfUnserializable(name, value)
+    searchParams.set(name, value)
+  }
+
+  searchParams.sort()
+  return searchParams.toString()
+}
+
+const throwIfUnserializable = (k: string, v: unknown): void => {
+  if (v == null) {
+    throw new UnserializableParamError(k, `is ${v} or contains ${v}`)
+  }
+
+  if (typeof v === 'function') {
+    throw new UnserializableParamError(
+      k,
+      'is a function or contains a function',
+    )
+  }
+
+  if (typeof v === 'object') {
+    throw new UnserializableParamError(k, 'is an object or contains an object')
+  }
+}
+
+export class UnserializableParamError extends Error {
+  constructor(name: string, message: string) {
+    super(`Could not serialize parameter: '${name}' ${message}`)
+    this.name = this.constructor.name
+    Error.captureStackTrace(this, this.constructor)
+  }
+}

package/src/lib/seam/connect/auth.ts

@@ -1,15 +1,19 @@
 import {
-  InvalidSeamHttpOptionsError,
   isSeamHttpOptionsWithApiKey,
   isSeamHttpOptionsWithClientSessionToken,
-  type SeamHttpOptions,
+  SeamHttpInvalidOptionsError,
   type SeamHttpOptionsWithApiKey,
   type SeamHttpOptionsWithClientSessionToken,
-} from './client-options.js'
+} from './options.js'
+import type { Options } from './parse-options.js'
 
 type Headers = Record<string, string>
 
-export const getAuthHeaders = (options: SeamHttpOptions): Headers => {
+export const getAuthHeaders = (options: Options): Headers => {
+  if ('publishableKey' in options) {
+    return getAuthHeadersForPublishableKey(options.publishableKey)
+  }
+
   if (isSeamHttpOptionsWithApiKey(options)) {
     return getAuthHeadersForApiKey(options)
   }
@@ -18,8 +22,8 @@ export const getAuthHeaders = (options: SeamHttpOptions): Headers => {
     return getAuthHeadersForClientSessionToken(options)
   }
 
-  throw new InvalidSeamHttpOptionsError(
-    'Must specify an apiKey or clientSessionToken',
+  throw new SeamHttpInvalidOptionsError(
+    'Must specify an apiKey, clientSessionToken, or publishableKey',
   )
 }
 
@@ -27,19 +31,29 @@ const getAuthHeadersForApiKey = ({
   apiKey,
 }: SeamHttpOptionsWithApiKey): Headers => {
   if (isClientSessionToken(apiKey)) {
-    throw new InvalidSeamTokenError(
+    throw new SeamHttpInvalidTokenError(
       'A Client Session Token cannot be used as an apiKey',
     )
   }
 
+  if (isJwt(apiKey)) {
+    throw new SeamHttpInvalidTokenError('A JWT cannot be used as an apiKey')
+  }
+
   if (isAccessToken(apiKey)) {
-    throw new InvalidSeamTokenError(
-      'An access token cannot be used as an apiKey',
+    throw new SeamHttpInvalidTokenError(
+      'An Access Token cannot be used as an apiKey',
+    )
+  }
+
+  if (isPublishableKey(apiKey)) {
+    throw new SeamHttpInvalidTokenError(
+      'A Publishable Key cannot be used as an apiKey',
     )
   }
 
-  if (isJwt(apiKey) || !isSeamToken(apiKey)) {
-    throw new InvalidSeamTokenError(
+  if (!isSeamToken(apiKey)) {
+    throw new SeamHttpInvalidTokenError(
       `Unknown or invalid apiKey format, expected token to start with ${tokenPrefix}`,
     )
   }
@@ -52,8 +66,26 @@ const getAuthHeadersForApiKey = ({
 const getAuthHeadersForClientSessionToken = ({
   clientSessionToken,
 }: SeamHttpOptionsWithClientSessionToken): Headers => {
+  if (isJwt(clientSessionToken)) {
+    throw new SeamHttpInvalidTokenError(
+      'A JWT cannot be used as a clientSessionToken',
+    )
+  }
+
+  if (isAccessToken(clientSessionToken)) {
+    throw new SeamHttpInvalidTokenError(
+      'An Access Token cannot be used as a clientSessionToken',
+    )
+  }
+
+  if (isPublishableKey(clientSessionToken)) {
+    throw new SeamHttpInvalidTokenError(
+      'A Publishable Key cannot be used as a clientSessionToken',
+    )
+  }
+
   if (!isClientSessionToken(clientSessionToken)) {
-    throw new InvalidSeamTokenError(
+    throw new SeamHttpInvalidTokenError(
       `Unknown or invalid clientSessionToken format, expected token to start with ${clientSessionTokenPrefix}`,
     )
   }
@@ -64,7 +96,37 @@ const getAuthHeadersForClientSessionToken = ({
   }
 }
 
-export class InvalidSeamTokenError extends Error {
+const getAuthHeadersForPublishableKey = (publishableKey: string): Headers => {
+  if (isJwt(publishableKey)) {
+    throw new SeamHttpInvalidTokenError(
+      'A JWT cannot be used as a publishableKey',
+    )
+  }
+
+  if (isAccessToken(publishableKey)) {
+    throw new SeamHttpInvalidTokenError(
+      'An Access Token cannot be used as a publishableKey',
+    )
+  }
+
+  if (isClientSessionToken(publishableKey)) {
+    throw new SeamHttpInvalidTokenError(
+      'A Client Session Token Key cannot be used as a publishableKey',
+    )
+  }
+
+  if (!isPublishableKey(publishableKey)) {
+    throw new SeamHttpInvalidTokenError(
+      `Unknown or invalid publishableKey format, expected token to start with ${publishableKeyTokenPrefix}`,
+    )
+  }
+
+  return {
+    'seam-publishable-key': publishableKey,
+  }
+}
+
+export class SeamHttpInvalidTokenError extends Error {
   constructor(message: string) {
     super(`SeamHttp received an invalid token: ${message}`)
     this.name = this.constructor.name
@@ -72,10 +134,29 @@ export class InvalidSeamTokenError extends Error {
   }
 }
 
+export const warnOnInsecureuserIdentifierKey = (
+  userIdentifierKey: string,
+): void => {
+  if (isEmail(userIdentifierKey)) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      ...[
+        'Using an email for the userIdentifierKey is insecure and may return an error in the future!',
+        'This is insecure because an email is common knowledge or easily guessed.',
+        'Use something with sufficient entropy known only to the owner of the client session.',
+        'For help choosing a user identifier key see',
+        'https://docs.seam.co/latest/seam-components/overview/get-started-with-client-side-components#3-select-a-user-identifier-key',
+      ],
+    )
+  }
+}
+
 const tokenPrefix = 'seam_'
 
 const clientSessionTokenPrefix = 'seam_cst'
 
+const publishableKeyTokenPrefix = 'seam_pk'
+
 const isClientSessionToken = (token: string): boolean =>
   token.startsWith(clientSessionTokenPrefix)
 
@@ -84,3 +165,10 @@ const isAccessToken = (token: string): boolean => token.startsWith('seam_at')
 const isJwt = (token: string): boolean => token.startsWith('ey')
 
 const isSeamToken = (token: string): boolean => token.startsWith(tokenPrefix)
+
+const isPublishableKey = (token: string): boolean =>
+  token.startsWith(publishableKeyTokenPrefix)
+
+// SOURCE: https://stackoverflow.com/a/46181
+const isEmail = (value: string): boolean =>
+  /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)

package/src/lib/seam/connect/client.ts

@@ -1,63 +1,31 @@
-import type { Axios } from 'axios'
-
-import { createAxiosClient } from './axios.js'
-import {
-  InvalidSeamHttpOptionsError,
-  isSeamHttpOptionsWithApiKey,
-  isSeamHttpOptionsWithClientSessionToken,
-  type SeamHttpOptions,
-  type SeamHttpOptionsWithApiKey,
-  type SeamHttpOptionsWithClientSessionToken,
-} from './client-options.js'
-import { LegacyWorkspacesHttp } from './legacy/workspaces.js'
-import { parseOptions } from './parse-options.js'
-import { WorkspacesHttp } from './routes/workspaces.js'
-
-export class SeamHttp {
-  client: Axios
-
-  #legacy: boolean
-
-  constructor(apiKeyOrOptions: string | SeamHttpOptions) {
-    const options = parseOptions(apiKeyOrOptions)
-    this.#legacy = options.enableLegacyMethodBehaivor
-    this.client = createAxiosClient(options)
-  }
-
-  static fromApiKey(
-    apiKey: SeamHttpOptionsWithApiKey['apiKey'],
-    options: Omit<SeamHttpOptionsWithApiKey, 'apiKey'> = {},
-  ): SeamHttp {
-    const opts = { ...options, apiKey }
-    if (!isSeamHttpOptionsWithApiKey(opts)) {
-      throw new InvalidSeamHttpOptionsError('Missing apiKey')
-    }
-    return new SeamHttp(opts)
-  }
-
-  static fromClientSessionToken(
-    clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'],
-    options: Omit<
-      SeamHttpOptionsWithClientSessionToken,
-      'clientSessionToken'
-    > = {},
-  ): SeamHttp {
-    const opts = { ...options, clientSessionToken }
-    if (!isSeamHttpOptionsWithClientSessionToken(opts)) {
-      throw new InvalidSeamHttpOptionsError('Missing clientSessionToken')
-    }
-    return new SeamHttp(opts)
-  }
-
-  // TODO
-  // static fromPublishableKey and deprecate getClientSessionToken
-
-  // TODO: Should we keep makeRequest?
-  // Better to implement error handling and wrapping in an error handler.
-  // makeRequest
-
-  get workspaces(): WorkspacesHttp {
-    if (this.#legacy) return new LegacyWorkspacesHttp(this.client)
-    return new WorkspacesHttp(this.client)
-  }
+import axios, { type Axios, type AxiosRequestConfig } from 'axios'
+import axiosRetry, { type AxiosRetry, exponentialDelay } from 'axios-retry'
+
+import { paramsSerializer } from 'lib/params-serializer.js'
+
+export type Client = Axios
+
+export interface ClientOptions {
+  axiosOptions?: AxiosRequestConfig
+  axiosRetryOptions?: AxiosRetryConfig
+  client?: Client
+}
+
+type AxiosRetryConfig = Parameters<AxiosRetry>[1]
+
+export const createClient = (options: ClientOptions): Axios => {
+  if (options.client != null) return options.client
+
+  const client = axios.create({
+    paramsSerializer,
+    ...options.axiosOptions,
+  })
+
+  axiosRetry(client, {
+    retries: 2,
+    retryDelay: exponentialDelay,
+    ...options.axiosRetryOptions,
+  })
+
+  return client
 }

package/src/lib/seam/connect/env.d.ts

@@ -0,0 +1,11 @@
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      SEAM_API_KEY?: string
+      SEAM_API_URL?: string
+      SEAM_ENDPOINT?: string
+    }
+  }
+}
+
+export {}

package/src/lib/seam/connect/index.ts

@@ -1 +1,2 @@
-export * from './client.js'
+export * from './options.js'
+export * from './seam-http.js'

package/src/lib/seam/connect/{client-options.ts → options.ts}

@@ -1,13 +1,39 @@
-import type { AxiosRequestConfig } from 'axios'
+import type { Client, ClientOptions } from './client.js'
 
 export type SeamHttpOptions =
+  | SeamHttpOptionsFromEnv
+  | SeamHttpOptionsWithClient
   | SeamHttpOptionsWithApiKey
   | SeamHttpOptionsWithClientSessionToken
 
-interface SeamHttpCommonOptions {
+interface SeamHttpCommonOptions extends ClientOptions {
   endpoint?: string
-  axiosOptions?: AxiosRequestConfig
-  enableLegacyMethodBehaivor?: boolean
+}
+
+export type SeamHttpFromPublishableKeyOptions = SeamHttpCommonOptions
+
+export type SeamHttpOptionsFromEnv = SeamHttpCommonOptions
+
+export interface SeamHttpOptionsWithClient {
+  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.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 {
@@ -18,10 +44,11 @@ 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 InvalidSeamHttpOptionsError(
-      'The clientSessionToken option cannot be used with the apiKey option.',
+    throw new SeamHttpInvalidOptionsError(
+      'The clientSessionToken option cannot be used with the apiKey option',
     )
   }
 
@@ -37,26 +64,21 @@ 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 InvalidSeamHttpOptionsError(
-      'The clientSessionToken option cannot be used with the apiKey option.',
+    throw new SeamHttpInvalidOptionsError(
+      'The clientSessionToken option cannot be used with the apiKey option',
     )
   }
 
   return true
 }
 
-export class InvalidSeamHttpOptionsError extends Error {
+export class SeamHttpInvalidOptionsError extends Error {
   constructor(message: string) {
     super(`SeamHttp received invalid options: ${message}`)
     this.name = this.constructor.name
     Error.captureStackTrace(this, this.constructor)
   }
 }
-
-// TODO: withSessionToken { sessionToken } or withMultiWorkspaceApiKey { apiKey }?
-// export interface SeamHttpOptionsWithSessionToken extends SeamHttpCommonOptions {
-//   workspaceId: string
-//   apiKey: string
-// }

package/src/lib/seam/connect/parse-options.ts

@@ -1,28 +1,69 @@
-import type { SeamHttpOptions } from './client-options.js'
+import { getAuthHeaders } from './auth.js'
+import type { ClientOptions } from './client.js'
+import {
+  isSeamHttpOptionsWithClient,
+  isSeamHttpOptionsWithClientSessionToken,
+  type SeamHttpOptions,
+} from './options.js'
+
+const defaultEndpoint = 'https://connect.getseam.com'
+
+export type Options = SeamHttpOptions & { publishableKey?: string }
+
 export const parseOptions = (
-  apiKeyOrOptions: string | SeamHttpOptions,
-): Required<SeamHttpOptions> => {
+  apiKeyOrOptions: string | Options,
+): ClientOptions => {
+  const options = getNormalizedOptions(apiKeyOrOptions)
+
+  if (isSeamHttpOptionsWithClient(options)) return options
+
+  return {
+    axiosOptions: {
+      baseURL: options.endpoint ?? getEndpointFromEnv() ?? defaultEndpoint,
+      withCredentials: isSeamHttpOptionsWithClientSessionToken(options),
+      ...options.axiosOptions,
+      headers: {
+        ...getAuthHeaders(options),
+        ...options.axiosOptions?.headers,
+      },
+    },
+    axiosRetryOptions: {
+      ...options.axiosRetryOptions,
+    },
+  }
+}
+
+const getNormalizedOptions = (
+  apiKeyOrOptions: string | Options,
+): SeamHttpOptions => {
   const options =
     typeof apiKeyOrOptions === 'string'
       ? { apiKey: apiKeyOrOptions }
       : apiKeyOrOptions
 
-  const endpoint =
-    options.endpoint ??
-    globalThis.process?.env?.['SEAM_ENDPOINT'] ??
-    globalThis.process?.env?.['SEAM_API_URL'] ??
-    'https://connect.getseam.com'
+  if (isSeamHttpOptionsWithClient(options)) return options
 
   const apiKey =
-    'apiKey' in options
-      ? options.apiKey
-      : globalThis.process?.env?.['SEAM_API_KEY']
+    'apiKey' in options ? options.apiKey : getApiKeyFromEnv(options)
 
   return {
     ...options,
     ...(apiKey != null ? { apiKey } : {}),
-    endpoint,
-    axiosOptions: options.axiosOptions ?? {},
-    enableLegacyMethodBehaivor: false,
   }
 }
+
+const getApiKeyFromEnv = (
+  options: SeamHttpOptions,
+): string | null | undefined => {
+  if ('clientSessionToken' in options && options.clientSessionToken != null) {
+    return null
+  }
+  return globalThis.process?.env?.SEAM_API_KEY
+}
+
+const getEndpointFromEnv = (): string | null | undefined => {
+  return (
+    globalThis.process?.env?.SEAM_ENDPOINT ??
+    globalThis.process?.env?.SEAM_API_URL
+  )
+}