@seamapi/http 2.17.0 → 2.19.0

package/src/lib/seam-http-error.ts

@@ -1,9 +1,25 @@
 import type { ApiError } from './api-error-types.js'
 
+/**
+ * Error thrown when the Seam API returns an error response.
+ */
 export class SeamHttpApiError extends Error {
+  /**
+   * Error type returned by the Seam API, e.g., `invalid_input`.
+   */
   code: string
+
   statusCode: number
+
+  /**
+   * Unique identifier of the request that failed.
+   * Provide this to Seam support when reporting an issue.
+   */
   requestId: string
+
+  /**
+   * Additional error-specific data returned by the Seam API, if any.
+   */
   data?: unknown
 
   constructor(error: ApiError, statusCode: number, requestId: string) {
@@ -17,12 +33,18 @@ export class SeamHttpApiError extends Error {
   }
 }
 
+/**
+ * Returns true if the error is a {@link SeamHttpApiError}.
+ */
 export const isSeamHttpApiError = (
   error: unknown,
 ): error is SeamHttpApiError => {
   return error instanceof SeamHttpApiError
 }
 
+/**
+ * Error thrown when the Seam API returns a 401 Unauthorized error response.
+ */
 export class SeamHttpUnauthorizedError extends SeamHttpApiError {
   override code: 'unauthorized'
   override statusCode: 401
@@ -38,14 +60,21 @@ export class SeamHttpUnauthorizedError extends SeamHttpApiError {
   }
 }
 
+/**
+ * Returns true if the error is a {@link SeamHttpUnauthorizedError}.
+ */
 export const isSeamHttpUnauthorizedError = (
   error: unknown,
 ): error is SeamHttpUnauthorizedError => {
   return error instanceof SeamHttpUnauthorizedError
 }
 
+/**
+ * Error thrown when the Seam API returns an `invalid_input` error response.
+ */
 export class SeamHttpInvalidInputError extends SeamHttpApiError {
   override code: 'invalid_input'
+
   readonly #validationErrors: NonNullable<ApiError['validation_errors']>
 
   constructor(error: ApiError, statusCode: number, requestId: string) {
@@ -55,11 +84,20 @@ export class SeamHttpInvalidInputError extends SeamHttpApiError {
     this.#validationErrors = error.validation_errors ?? {}
   }
 
+  /**
+   * Returns the validation error messages for the request parameter,
+   * or an empty array if the parameter had no validation errors.
+   *
+   * @param paramName - Name of the request parameter.
+   */
   getValidationErrorMessages(paramName: string): string[] {
     return this.#validationErrors[paramName]?._errors ?? []
   }
 }
 
+/**
+ * Returns true if the error is a {@link SeamHttpInvalidInputError}.
+ */
 export const isSeamHttpInvalidInputError = (
   error: unknown,
 ): error is SeamHttpInvalidInputError => {

package/src/lib/seam-http-request.ts

@@ -29,6 +29,20 @@ interface SeamHttpRequestConfig<TResponseKey> {
   readonly requiredParameterNames?: readonly string[]
 }
 
+/**
+ * A lazy request to the Seam API.
+ *
+ * Creating a SeamHttpRequest does not send anything over the network.
+ * The request is sent once `execute` is called,
+ * or when the request is awaited like a Promise,
+ * e.g., with `await`, `then`, `catch`, or `finally`.
+ * When the response contains an action attempt,
+ * awaiting the request also waits for the action attempt to resolve
+ * according to the `waitForActionAttempt` option.
+ *
+ * Before sending, the request may be inspected
+ * with `url`, `pathname`, `method`, `params`, and `body`.
+ */
 export class SeamHttpRequest<
   const TResponse,
   const TResponseKey extends keyof TResponse | undefined,
@@ -48,6 +62,10 @@ export class SeamHttpRequest<
     this.#config = config
   }
 
+  /**
+   * The key of the API response object containing the response data,
+   * or undefined if the endpoint returns an empty response.
+   */
   public get responseKey(): TResponseKey {
     return this.#config.responseKey
   }
@@ -56,6 +74,9 @@ export class SeamHttpRequest<
     return this.#config.hasPagination ?? false
   }
 
+  /**
+   * The full request URL including any serialized query parameters.
+   */
   public get url(): URL {
     const { client } = this.#parent
 
@@ -92,6 +113,12 @@ export class SeamHttpRequest<
     return this.#config.body
   }
 
+  /**
+   * Sends the request and returns the response data.
+   * If the response contains an action attempt,
+   * waits for the action attempt to resolve
+   * according to the `waitForActionAttempt` option.
+   */
   async execute(): Promise<
     TResponseKey extends keyof TResponse ? TResponse[TResponseKey] : undefined
   > {
@@ -130,6 +157,10 @@ export class SeamHttpRequest<
     return data
   }
 
+  /**
+   * Sends the request and returns the entire response body
+   * without waiting for any action attempt to resolve.
+   */
   async fetchResponse(): Promise<TResponse> {
     assertValidRequestParameters(
       this.#config.parameters,

package/src/lib/seam-paginator.ts

@@ -9,6 +9,9 @@ interface SeamPaginatorParent {
 
 declare const $brand: unique symbol
 
+/**
+ * Opaque cursor identifying a page of results returned by the Seam API.
+ */
 export type SeamPageCursor = string & { [$brand]: 'SeamPageCursor' }
 
 interface Pagination {
@@ -17,6 +20,15 @@ interface Pagination {
   readonly nextPageUrl: string | null
 }
 
+/**
+ * Iterates over paginated results from Seam API list endpoints.
+ *
+ * Create a SeamPaginator with the client's `createPaginator` method.
+ * Fetch pages manually with `firstPage` and `nextPage`,
+ * iterate over pages with `for await`,
+ * iterate over items across all pages with `flatten`,
+ * or collect every item into a single array with `flattenToArray`.
+ */
 export class SeamPaginator<
   const TResponse,
   const TResponseKey extends keyof TResponse,
@@ -37,12 +49,19 @@ export class SeamPaginator<
     this.#request = request
   }
 
+  /**
+   * Fetches the first page of results along with the pagination state.
+   */
   async firstPage(): Promise<
     [EnsureReadonlyArray<TResponse[TResponseKey]>, Pagination]
   > {
     return await this.#fetch()
   }
 
+  /**
+   * Fetches the next page of results
+   * using the nextPageCursor returned with a previous page.
+   */
   async nextPage(
     nextPageCursor: Pagination['nextPageCursor'],
   ): Promise<[EnsureReadonlyArray<TResponse[TResponseKey]>, Pagination]> {
@@ -104,6 +123,9 @@ export class SeamPaginator<
     ] as const
   }
 
+  /**
+   * Fetches every page and returns all items in a single array.
+   */
   async flattenToArray(): Promise<
     EnsureReadonlyArray<TResponse[TResponseKey]>
   > {
@@ -117,6 +139,9 @@ export class SeamPaginator<
     return items as EnsureReadonlyArray<TResponse[TResponseKey]>
   }
 
+  /**
+   * Yields each item across all pages, fetching the next page as needed.
+   */
   async *flatten(): AsyncGenerator<
     EnsureReadonlyArray<TResponse[TResponseKey]>
   > {
@@ -132,6 +157,9 @@ export class SeamPaginator<
     }
   }
 
+  /**
+   * Yields each page of items, fetching the next page as needed.
+   */
   async *[Symbol.asyncIterator](): AsyncGenerator<
     EnsureReadonlyArray<TResponse[TResponseKey]>
   > {

package/src/lib/version.ts

@@ -1,3 +1,3 @@
-const seamapiJavascriptHttpVersion = '2.17.0'
+const seamapiJavascriptHttpVersion = '2.19.0'
 
 export default seamapiJavascriptHttpVersion