@seamapi/http 1.24.0 → 1.25.0

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

@@ -1,3 +1,4 @@
+import type { ActionAttempt } from '@seamapi/types/connect'
 import { serializeUrlSearchParams } from '@seamapi/url-search-params-serializer'
 import type { Method } from 'axios'
 
@@ -12,7 +13,7 @@ interface SeamHttpRequestParent {
 }
 
 interface SeamHttpRequestConfig<TResponseKey> {
-  readonly path: string
+  readonly pathname: string
   readonly method: Method
   readonly body?: unknown
   readonly params?: undefined | Record<string, unknown>
@@ -47,7 +48,6 @@ export class SeamHttpRequest<
 
   public get url(): URL {
     const { client } = this.#parent
-    const { params } = this.#config
 
     const serializer =
       typeof client.defaults.paramsSerializer === 'function'
@@ -56,19 +56,28 @@ export class SeamHttpRequest<
 
     const origin = getUrlPrefix(client.defaults.baseURL ?? '')
 
-    const pathname = this.#config.path.startsWith('/')
-      ? this.#config.path
-      : `/${this.#config.path}`
-
-    const path = params == null ? pathname : `${pathname}?${serializer(params)}`
+    const path =
+      this.params == null
+        ? this.pathname
+        : `${this.pathname}?${serializer(this.params)}`
 
     return new URL(`${origin}${path}`)
   }
 
+  public get pathname(): string {
+    return this.#config.pathname.startsWith('/')
+      ? this.#config.pathname
+      : `/${this.#config.pathname}`
+  }
+
   public get method(): Method {
     return this.#config.method
   }
 
+  public get params(): undefined | Record<string, unknown> {
+    return this.#config.params
+  }
+
   public get body(): unknown {
     return this.#config.body
   }
@@ -76,37 +85,50 @@ export class SeamHttpRequest<
   async execute(): Promise<
     TResponseKey extends keyof TResponse ? TResponse[TResponseKey] : undefined
   > {
-    const { client } = this.#parent
-    const response = await client.request({
-      url: this.#config.path,
-      method: this.#config.method,
-      data: this.#config.body,
-      params: this.#config.params,
-    })
+    const response = await this.fetchResponse()
+
+    type Response = TResponseKey extends keyof TResponse
+      ? TResponse[TResponseKey]
+      : undefined
+
     if (this.responseKey === undefined) {
-      return undefined as TResponseKey extends keyof TResponse
-        ? TResponse[TResponseKey]
-        : undefined
+      return undefined as Response
     }
-    const data = response.data[this.responseKey]
+
+    const data = response[this.responseKey] as unknown as Response
+
     if (this.responseKey === 'action_attempt') {
       const waitForActionAttempt =
         this.#config.options?.waitForActionAttempt ??
         this.#parent.defaults.waitForActionAttempt
+
       if (waitForActionAttempt !== false) {
-        return await resolveActionAttempt(
-          data,
-          SeamHttpActionAttempts.fromClient(client, {
+        const actionAttempt = await resolveActionAttempt(
+          data as unknown as ActionAttempt,
+          SeamHttpActionAttempts.fromClient(this.#parent.client, {
             ...this.#parent.defaults,
             waitForActionAttempt: false,
           }),
           typeof waitForActionAttempt === 'boolean' ? {} : waitForActionAttempt,
         )
+        return actionAttempt as Response
       }
     }
+
     return data
   }
 
+  async fetchResponse(): Promise<TResponse> {
+    const { client } = this.#parent
+    const response = await client.request({
+      url: this.pathname,
+      method: this.method,
+      data: this.body,
+      params: this.params,
+    })
+    return response.data as unknown as TResponse
+  }
+
   async then<
     TResult1 = TResponseKey extends keyof TResponse
       ? TResponse[TResponseKey]
@@ -122,7 +144,7 @@ export class SeamHttpRequest<
       | null
       | undefined,
     onrejected?:
-      | ((reason: any) => TResult2 | PromiseLike<TResult2>)
+      | ((reason: unknown) => TResult2 | PromiseLike<TResult2>)
       | null
       | undefined,
   ): Promise<TResult1 | TResult2> {
@@ -131,7 +153,7 @@ export class SeamHttpRequest<
 
   async catch<TResult = never>(
     onrejected?:
-      | ((reason: any) => TResult | PromiseLike<TResult>)
+      | ((reason: unknown) => TResult | PromiseLike<TResult>)
       | null
       | undefined,
   ): Promise<

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

@@ -40,6 +40,8 @@ import {
   SeamHttpWebhooks,
   SeamHttpWorkspaces,
 } from './routes/index.js'
+import type { SeamHttpRequest } from './seam-http-request.js'
+import { SeamPaginator } from './seam-paginator.js'
 
 export class SeamHttp {
   client: Client
@@ -143,6 +145,12 @@ export class SeamHttp {
     return new SeamHttp(constructorOptions)
   }
 
+  createPaginator<const TResponse, const TResponseKey extends keyof TResponse>(
+    request: SeamHttpRequest<TResponse, TResponseKey>,
+  ): SeamPaginator<TResponse, TResponseKey> {
+    return new SeamPaginator<TResponse, TResponseKey>(this, request)
+  }
+
   async updateClientSessionToken(
     clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'],
   ): Promise<void> {

package/src/lib/seam/connect/seam-paginator.ts

@@ -0,0 +1,155 @@
+import type { Client } from './client.js'
+import type { SeamHttpRequestOptions } from './options.js'
+import { SeamHttpRequest } from './seam-http-request.js'
+
+interface SeamPaginatorParent {
+  readonly client: Client
+  readonly defaults: Required<SeamHttpRequestOptions>
+}
+
+declare const $brand: unique symbol
+
+type PageCursor = string & { [$brand]: 'SeamPageCursor' }
+
+interface Pagination {
+  readonly hasNextPage: boolean
+  readonly nextPageCursor: PageCursor | null
+  readonly nextPageUrl: string | null
+}
+
+export class SeamPaginator<
+  const TResponse,
+  const TResponseKey extends keyof TResponse,
+> implements AsyncIterable<EnsureReadonlyArray<TResponse[TResponseKey]>>
+{
+  readonly #request: SeamHttpRequest<TResponse, TResponseKey>
+  readonly #parent: SeamPaginatorParent
+
+  constructor(
+    parent: SeamPaginatorParent,
+    request: SeamHttpRequest<TResponse, TResponseKey>,
+  ) {
+    if (request.responseKey == null) {
+      throw new Error(
+        `The ${request.pathname} endpoint does not support pagination`,
+      )
+    }
+    this.#parent = parent
+    this.#request = request
+  }
+
+  async firstPage(): Promise<
+    [EnsureReadonlyArray<TResponse[TResponseKey]>, Pagination]
+  > {
+    return await this.#fetch()
+  }
+
+  async nextPage(
+    nextPageCursor: Pagination['nextPageCursor'],
+  ): Promise<[EnsureReadonlyArray<TResponse[TResponseKey]>, Pagination]> {
+    if (nextPageCursor == null) {
+      throw new Error('Cannot get the next page with a null nextPageCursor')
+    }
+
+    return await this.#fetch(nextPageCursor)
+  }
+
+  async #fetch(
+    nextPageCursor?: Pagination['nextPageCursor'],
+  ): Promise<[EnsureReadonlyArray<TResponse[TResponseKey]>, Pagination]> {
+    const responseKey = this.#request.responseKey
+
+    if (responseKey == null) {
+      throw new Error('Cannot paginate a response without a responseKey')
+    }
+
+    const request = new SeamHttpRequest<TResponse, TResponseKey>(this.#parent, {
+      pathname: this.#request.pathname,
+      method: this.#request.method,
+      responseKey,
+      params:
+        this.#request.params != null
+          ? { ...this.#request.params, page_cursor: nextPageCursor }
+          : undefined,
+      body:
+        this.#request.body != null
+          ? { ...this.#request.body, page_cursor: nextPageCursor }
+          : undefined,
+    })
+
+    const response = await request.fetchResponse()
+    const data = response[responseKey]
+
+    const paginationData =
+      response != null &&
+      typeof response === 'object' &&
+      'pagination' in response
+        ? (response.pagination as PaginationData)
+        : null
+
+    const pagination: Pagination = {
+      hasNextPage: paginationData?.has_next_page ?? false,
+      nextPageCursor: paginationData?.next_page_cursor ?? null,
+      nextPageUrl: paginationData?.next_page_url ?? null,
+    }
+
+    if (!Array.isArray(data)) {
+      throw new Error(
+        `Expected an array response for ${String(responseKey)} but got ${String(typeof data)}`,
+      )
+    }
+
+    return [
+      data as EnsureReadonlyArray<TResponse[TResponseKey]>,
+      pagination,
+    ] as const
+  }
+
+  async flattenToArray(): Promise<
+    EnsureReadonlyArray<TResponse[TResponseKey]>
+  > {
+    const items = [] as EnsureMutableArray<TResponse[TResponseKey]>
+    let [current, pagination] = await this.firstPage()
+    items.push(...current)
+    while (pagination.hasNextPage) {
+      ;[current, pagination] = await this.nextPage(pagination.nextPageCursor)
+      items.push(...current)
+    }
+    return items as EnsureReadonlyArray<TResponse[TResponseKey]>
+  }
+
+  async *flatten(): AsyncGenerator<
+    EnsureReadonlyArray<TResponse[TResponseKey]>
+  > {
+    let [current, pagination] = await this.firstPage()
+    for (const item of current) {
+      yield item
+    }
+    while (pagination.hasNextPage) {
+      ;[current, pagination] = await this.nextPage(pagination.nextPageCursor)
+      for (const item of current) {
+        yield item
+      }
+    }
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<
+    EnsureReadonlyArray<TResponse[TResponseKey]>
+  > {
+    let [current, pagination] = await this.firstPage()
+    yield current
+    while (pagination.hasNextPage) {
+      ;[current, pagination] = await this.nextPage(pagination.nextPageCursor)
+      yield current
+    }
+  }
+}
+
+type EnsureReadonlyArray<T> = T extends readonly any[] ? T : never
+type EnsureMutableArray<T> = T extends any[] ? T : never
+
+interface PaginationData {
+  has_next_page: boolean
+  next_page_cursor: PageCursor | null
+  next_page_url: string | null
+}

package/src/lib/version.ts

@@ -1,3 +1,3 @@
-const seamapiJavascriptHttpVersion = '1.24.0'
+const seamapiJavascriptHttpVersion = '1.25.0'
 
 export default seamapiJavascriptHttpVersion