feat: Add default client request options (#23)

Author: razor-x

README.md

@@ -151,7 +151,9 @@ Some asynchronous operations, e.g., unlocking a door, return an [action attempt]
 Seam tracks the progress of requested operation and updates the action attempt.
 
 To make working with action attempts more convenient for applications,
-this library provides the `waitForActionAttempt` option:
+this library provides the `waitForActionAttempt` option.
+
+Pass the option per-request,
 
 ```ts
 await seam.locks.unlockDoor(
@@ -162,6 +164,17 @@ await seam.locks.unlockDoor(
 )
 ```
 
+or set the default option for the client:
+
+```ts
+const seam = new SeamHttp({
+  apiKey: 'your-api-key',
+  waitForActionAttempt: true,
+})
+
+await seam.locks.unlockDoor({ device_id })
+```
+
 Using the `waitForActionAttempt` option:
 
 - Polls the action attempt up to the `timeout`

generate-routes.ts

@@ -254,11 +254,14 @@ import {
   type SeamHttpOptionsWithClientSessionToken,
   type SeamHttpOptionsWithConsoleSessionToken,
   type SeamHttpOptionsWithPersonalAccessToken,
+  type SeamHttpRequestOptions,
 } from 'lib/seam/connect/options.js'
-import { parseOptions } from 'lib/seam/connect/parse-options.js'
+import {
+  limitToSeamHttpRequestOptions,
+  parseOptions
+} from 'lib/seam/connect/parse-options.js'
 import {
   resolveActionAttempt,
-  type ResolveActionAttemptOptions,
 } from 'lib/seam/connect/resolve-action-attempt.js'
 
 ${
@@ -291,6 +294,7 @@ const renderClass = (
   `
 export class SeamHttp${pascalCase(namespace)} {
   client: Client
+  readonly defaults: Required<SeamHttpRequestOptions>
 
   ${constructors
     .replaceAll(': SeamHttp ', `: SeamHttp${pascalCase(namespace)} `)
@@ -342,10 +346,11 @@ const renderClassMethod = ({
     })
     ${
       resource === 'action_attempt'
-        ? `if (waitForActionAttempt != null && waitForActionAttempt !== false) {
+        ? `const waitForActionAttempt = options.waitForActionAttempt ?? this.defaults.waitForActionAttempt
+          if (waitForActionAttempt !== false) {
             return resolveActionAttempt(
               data.${resource},
-              SeamHttpActionAttempts.fromClient(this.client),
+              SeamHttpActionAttempts.fromClient(this.client, { ...this.defaults, waitForActionAttempt: false }),
               typeof waitForActionAttempt === 'boolean' ? {} : waitForActionAttempt,
             )
           }`
@@ -359,9 +364,9 @@ const renderClassMethodOptions = ({
   resource,
 }: Pick<Endpoint, 'resource'>): string => {
   if (resource === 'action_attempt') {
-    return `{ waitForActionAttempt = false }: ${renderClassMethodOptionsTypeDef(
-      { resource },
-    )} = {},`
+    return `options: ${renderClassMethodOptionsTypeDef({
+      resource,
+    })} = {},`
   }
   return ''
 }
@@ -376,11 +381,7 @@ const renderClassMethodOptionsTypeDef = ({
   resource,
 }: Pick<Endpoint, 'resource'>): string => {
   if (resource === 'action_attempt') {
-    return `
-      {
-        waitForActionAttempt?: boolean | Partial<ResolveActionAttemptOptions>
-      }
-    `
+    return "Pick<SeamHttpRequestOptions, 'waitForActionAttempt'>"
   }
   return 'never'
 }
@@ -394,7 +395,7 @@ const renderSubresourceMethod = (
   )}${pascalCase(subresource)} {
     return SeamHttp${pascalCase(namespace)}${pascalCase(
       subresource,
-    )}.fromClient(this.client)
+    )}.fromClient(this.client, this.defaults)
   }
 `
 

src/lib/seam/connect/client.ts

@@ -12,14 +12,11 @@ export type Client = AxiosInstance
 export interface ClientOptions {
   axiosOptions?: AxiosRequestConfig
   axiosRetryOptions?: AxiosRetryConfig
-  client?: Client
 }
 
 type AxiosRetryConfig = Parameters<AxiosRetry>[1]
 
 export const createClient = (options: ClientOptions): AxiosInstance => {
-  if (options.client != null) return options.client
-
   const client = axios.create({
     paramsSerializer,
     ...options.axiosOptions,

src/lib/seam/connect/options.ts

@@ -1,4 +1,6 @@
 import type { Client, ClientOptions } from './client.js'
+import { isSeamHttpRequestOption } from './parse-options.js'
+import type { ResolveActionAttemptOptions } from './resolve-action-attempt.js'
 
 export type SeamHttpMultiWorkspaceOptions =
   | SeamHttpMultiWorkspaceOptionsWithClient
@@ -13,16 +15,21 @@ export type SeamHttpOptions =
   | SeamHttpOptionsWithConsoleSessionToken
   | SeamHttpOptionsWithPersonalAccessToken
 
-interface SeamHttpCommonOptions extends ClientOptions {
+interface SeamHttpCommonOptions extends ClientOptions, SeamHttpRequestOptions {
   endpoint?: string
 }
 
+export interface SeamHttpRequestOptions {
+  waitForActionAttempt?: boolean | ResolveActionAttemptOptions
+}
+
 export interface SeamHttpFromPublishableKeyOptions
   extends SeamHttpCommonOptions {}
 
 export interface SeamHttpOptionsFromEnv extends SeamHttpCommonOptions {}
 
-export interface SeamHttpMultiWorkspaceOptionsWithClient {
+export interface SeamHttpMultiWorkspaceOptionsWithClient
+  extends SeamHttpRequestOptions {
   client: Client
 }
 
@@ -31,7 +38,7 @@ export const isSeamHttpMultiWorkspaceOptionsWithClient = (
 ): options is SeamHttpMultiWorkspaceOptionsWithClient =>
   isSeamHttpOptionsWithClient(options)
 
-export interface SeamHttpOptionsWithClient {
+export interface SeamHttpOptionsWithClient extends SeamHttpRequestOptions {
   client: Client
 }
 
@@ -42,7 +49,7 @@ export const isSeamHttpOptionsWithClient = (
   if (options.client == null) return false
 
   const keys = Object.keys(options).filter((k) => k !== 'client')
-  if (keys.length > 0) {
+  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(
         ', ',

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

@@ -1,13 +1,14 @@
 import version from 'lib/version.js'
 
 import { getAuthHeaders } from './auth.js'
-import type { ClientOptions } from './client.js'
+import type { Client, ClientOptions } from './client.js'
 import {
   isSeamHttpMultiWorkspaceOptionsWithClient,
   isSeamHttpOptionsWithClient,
   isSeamHttpOptionsWithClientSessionToken,
   type SeamHttpMultiWorkspaceOptions,
   type SeamHttpOptions,
+  type SeamHttpRequestOptions,
 } from './options.js'
 
 const defaultEndpoint = 'https://connect.getseam.com'
@@ -21,15 +22,20 @@ export type Options =
   | SeamHttpMultiWorkspaceOptions
   | (SeamHttpOptions & { publishableKey?: string })
 
+type ParsedOptions = Required<
+  (ClientOptions | { client: Client }) & SeamHttpRequestOptions
+>
+
 export const parseOptions = (
   apiKeyOrOptions: string | Options,
-): ClientOptions => {
+): ParsedOptions => {
   const options = getNormalizedOptions(apiKeyOrOptions)
 
   if (isSeamHttpOptionsWithClient(options)) return options
   if (isSeamHttpMultiWorkspaceOptionsWithClient(options)) return options
 
   return {
+    ...options,
     axiosOptions: {
       baseURL: options.endpoint ?? getEndpointFromEnv() ?? defaultEndpoint,
       withCredentials: isSeamHttpOptionsWithClientSessionToken(options),
@@ -48,20 +54,30 @@ export const parseOptions = (
 
 const getNormalizedOptions = (
   apiKeyOrOptions: string | Options,
-): SeamHttpOptions => {
+): SeamHttpOptions & Required<SeamHttpRequestOptions> => {
   const options =
     typeof apiKeyOrOptions === 'string'
       ? { apiKey: apiKeyOrOptions }
       : apiKeyOrOptions
 
-  if (isSeamHttpOptionsWithClient(options)) return options
+  const requestOptions = {
+    waitForActionAttempt: options.waitForActionAttempt ?? false,
+  }
+
+  if (isSeamHttpOptionsWithClient(options)) {
+    return {
+      ...options,
+      ...requestOptions,
+    }
+  }
 
   const apiKey =
     'apiKey' in options ? options.apiKey : getApiKeyFromEnv(options)
 
   return {
     ...options,
     ...(apiKey != null ? { apiKey } : {}),
+    ...requestOptions,
   }
 }
 
@@ -80,3 +96,26 @@ const getEndpointFromEnv = (): string | null | undefined => {
     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 const isSeamHttpRequestOption = (
+  key: string,
+): key is keyof SeamHttpRequestOptions => {
+  const keys: Record<keyof SeamHttpRequestOptions, true> = {
+    waitForActionAttempt: true,
+  }
+  return Object.keys(keys).includes(key)
+}