Merge branch 'main' into claude/js-sdk-audit-6x115l-l8a-params-serializer

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B8xeJm2Hd923k8uo6eoFd2

Author: claude

.c8rc.json

@@ -1,6 +1,5 @@
 {
   "exclude": [
-    "**/index.ts",
     "package/**/*.ts",
     "examples/**/*.ts",
     "**/*.test.ts",

README.md

@@ -350,7 +350,7 @@ const pages = seam.createPaginator(
 )
 
 for await (const device of pages.flatten()) {
-  console.log(devices.name)
+  console.log(device.display_name)
 }
 ```
 
@@ -474,7 +474,8 @@ default.
 
 The Axios client and retry behavior may be configured with custom initiation options
 via [`axiosOptions`][axiosOptions] and [`axiosRetryOptions`][axiosRetryOptions].
-Options are deep merged with the default options.
+Options are shallow merged with the default options:
+each provided top-level option replaces the default value.
 
 By default, the SDK makes up to three attempts: the initial request and two
 retries. Retries are limited to `GET`, `HEAD`, `OPTIONS`, `PUT`, and `DELETE`
@@ -537,6 +538,12 @@ console.log(`${request.method} ${request.url}`, JSON.stringify(request.body))
 const devices = await request.execute()
 ```
 
+A `SeamHttpRequest` is sent at most once.
+Awaiting the same request again,
+or calling `execute`, `then`, `catch`, or `finally` more than once,
+always returns the result of the first execution
+and never repeats the HTTP request.
+
 #### Serializing URL search params
 
 The Seam API parses URL search params as complex types.

package-lock.json

@@ -1,14 +1,14 @@
 {
   "name": "@seamapi/http",
-  "version": "2.23.0",
+  "version": "2.23.5",
   "description": "JavaScript HTTP client for the Seam API written in TypeScript.",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
   "exports": {
     ".": {
       "types": "./index.d.ts",
-      "import": "./index.js"
+      "default": "./index.js"
     },
     "./connect": {
       "types": "./index.d.ts",

package.json

@@ -103,3 +103,38 @@ export const isSeamHttpInvalidInputError = (
 ): error is SeamHttpInvalidInputError => {
   return error instanceof SeamHttpInvalidInputError
 }
+
+/**
+ * Error thrown when the Seam API returns a success response
+ * with an unexpected shape,
+ * e.g., a response missing the expected response key.
+ */
+export class SeamHttpInvalidResponseError extends Error {
+  /**
+   * Path of the endpoint that returned the invalid response.
+   */
+  path: string
+
+  /**
+   * Key expected to contain the response data.
+   */
+  responseKey: string
+
+  constructor(path: string, responseKey: string, reason: string) {
+    super(
+      `Seam returned an invalid response for ${path}: expected "${responseKey}", ${reason}`,
+    )
+    this.name = this.constructor.name
+    this.path = path
+    this.responseKey = responseKey
+  }
+}
+
+/**
+ * Returns true if the error is a {@link SeamHttpInvalidResponseError}.
+ */
+export const isSeamHttpInvalidResponseError = (
+  error: unknown,
+): error is SeamHttpInvalidResponseError => {
+  return error instanceof SeamHttpInvalidResponseError
+}

src/lib/seam-http-error.ts

@@ -8,6 +8,7 @@ import {
   resolveActionAttempt,
 } from './resolve-action-attempt.js'
 import type { ActionAttempt } from './resources/action-attempt.js'
+import { SeamHttpInvalidResponseError } from './seam-http-error.js'
 import { serializeUrlSearchParams } from './url-search-params-serializer.js'
 
 interface SeamHttpRequestParent {
@@ -36,6 +37,11 @@ interface SeamHttpRequestConfig<TResponseKey> {
  * 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`.
+ * The request is sent at most once:
+ * awaiting the same SeamHttpRequest again,
+ * or calling `execute`, `then`, `catch`, or `finally` more than once,
+ * always returns the result of the first execution
+ * and never repeats the HTTP request.
  * When the response contains an action attempt,
  * awaiting the request also waits for the action attempt to resolve
  * according to the `waitForActionAttempt` option.
@@ -54,6 +60,12 @@ export class SeamHttpRequest<
   readonly #parent: SeamHttpRequestParent
   readonly #config: SeamHttpRequestConfig<TResponseKey>
 
+  #executePromise: Promise<
+    TResponseKey extends keyof TResponse ? TResponse[TResponseKey] : undefined
+  > | null = null
+
+  #fetchResponsePromise: Promise<TResponse> | null = null
+
   constructor(
     parent: SeamHttpRequestParent,
     config: SeamHttpRequestConfig<TResponseKey>,
@@ -115,9 +127,19 @@ export class SeamHttpRequest<
    * If the response contains an action attempt,
    * waits for the action attempt to resolve
    * according to the `waitForActionAttempt` option.
+   * The request is sent at most once:
+   * calling this method again returns the result of the first call
+   * and never repeats the HTTP request.
    */
   async execute(): Promise<
     TResponseKey extends keyof TResponse ? TResponse[TResponseKey] : undefined
+  > {
+    this.#executePromise ??= this.#execute()
+    return await this.#executePromise
+  }
+
+  async #execute(): Promise<
+    TResponseKey extends keyof TResponse ? TResponse[TResponseKey] : undefined
   > {
     const response = await this.fetchResponse()
 
@@ -129,7 +151,11 @@ export class SeamHttpRequest<
       return undefined as Response
     }
 
-    const data = response[this.responseKey] as unknown as Response
+    const data = readResponseData(
+      response,
+      this.responseKey,
+      this.pathname,
+    ) as Response
 
     if (this.responseKey === 'action_attempt') {
       const waitForActionAttempt =
@@ -157,8 +183,16 @@ export class SeamHttpRequest<
   /**
    * Sends the request and returns the entire response body
    * without waiting for any action attempt to resolve.
+   * The request is sent at most once:
+   * calling this method again returns the result of the first call
+   * and never repeats the HTTP request.
    */
   async fetchResponse(): Promise<TResponse> {
+    this.#fetchResponsePromise ??= this.#fetchResponse()
+    return await this.#fetchResponsePromise
+  }
+
+  async #fetchResponse(): Promise<TResponse> {
     assertValidRequestParameters(
       this.#config.parameters,
       this.pathname,
@@ -229,8 +263,40 @@ const getParamsSerializer = (
   return serializeUrlSearchParams
 }
 
+/**
+ * Reads the response data at the response key,
+ * throwing a {@link SeamHttpInvalidResponseError} for a success response
+ * that is not an object or does not contain the response key.
+ */
+export const readResponseData = <
+  TResponse,
+  TResponseKey extends keyof TResponse,
+>(
+  response: TResponse,
+  responseKey: TResponseKey,
+  path: string,
+): TResponse[TResponseKey] => {
+  if (response == null || typeof response !== 'object') {
+    throw new SeamHttpInvalidResponseError(
+      path,
+      String(responseKey),
+      `got ${response === null ? 'null' : typeof response} instead of a response object`,
+    )
+  }
+
+  if (!(responseKey in response)) {
+    throw new SeamHttpInvalidResponseError(
+      path,
+      String(responseKey),
+      'which the response does not contain',
+    )
+  }
+
+  return response[responseKey]
+}
+
 const getUrlPrefix = (input: string): string => {
-  if (canParseUrl(input)) {
+  if (isAbsoluteHttpUrl(input)) {
     const url = new URL(input).toString()
     if (url.endsWith('/')) return url.slice(0, -1)
     return url
@@ -246,11 +312,13 @@ const getUrlPrefix = (input: string): string => {
   )
 }
 
-// UPSTREAM: Prefer URL.canParse when it has wider support.
-// https://caniuse.com/mdn-api_url_canparse_static
-const canParseUrl = (input: string): boolean => {
+// An input without an http or https scheme, e.g., localhost:3000,
+// may still parse as a URL with an unintended scheme, e.g., localhost:,
+// and must not be treated as an absolute URL.
+const isAbsoluteHttpUrl = (input: string): boolean => {
   try {
-    return new URL(input) != null
+    const { protocol } = new URL(input)
+    return protocol === 'http:' || protocol === 'https:'
   } catch {
     return false
   }

src/lib/seam-http-request.ts

@@ -1,6 +1,7 @@
 import type { Client } from './client.js'
 import type { SeamHttpRequestOptions } from './options.js'
-import { SeamHttpRequest } from './seam-http-request.js'
+import { SeamHttpInvalidResponseError } from './seam-http-error.js'
+import { readResponseData, SeamHttpRequest } from './seam-http-request.js'
 
 interface SeamPaginatorParent {
   readonly client: Client
@@ -96,27 +97,38 @@ export class SeamPaginator<
     })
 
     const response = await request.fetchResponse()
-    const data = response[responseKey]
+    const data = readResponseData(response, responseKey, request.pathname)
 
-    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 SeamHttpInvalidResponseError(
+        request.pathname,
+        String(responseKey),
+        `got ${data === null ? 'null' : typeof data} instead of a list`,
+      )
     }
 
-    if (!Array.isArray(data)) {
-      throw new Error(
-        `Expected an array response for ${String(responseKey)} but got ${String(typeof data)}`,
+    const paginationData = readResponseData(
+      response as { pagination: unknown },
+      'pagination',
+      request.pathname,
+    )
+
+    if (paginationData === null || typeof paginationData !== 'object') {
+      throw new SeamHttpInvalidResponseError(
+        request.pathname,
+        'pagination',
+        `got ${paginationData === null ? 'null' : typeof paginationData} instead of a pagination object`,
       )
     }
 
+    const paginationResponse = paginationData as PaginationData
+
+    const pagination: Pagination = {
+      hasNextPage: paginationResponse.has_next_page ?? false,
+      nextPageCursor: paginationResponse.next_page_cursor ?? null,
+      nextPageUrl: paginationResponse.next_page_url ?? null,
+    }
+
     return [
       data as EnsureReadonlyArray<TResponse[TResponseKey]>,
       pagination,
@@ -142,9 +154,7 @@ export class SeamPaginator<
   /**
    * Yields each item across all pages, fetching the next page as needed.
    */
-  async *flatten(): AsyncGenerator<
-    EnsureReadonlyArray<TResponse[TResponseKey]>
-  > {
+  async *flatten(): AsyncGenerator<ElementOfArray<TResponse[TResponseKey]>> {
     let [current, pagination] = await this.firstPage()
     for (const item of current) {
       yield item
@@ -174,6 +184,8 @@ export class SeamPaginator<
 
 type EnsureReadonlyArray<T> = T extends readonly any[] ? T : never
 type EnsureMutableArray<T> = T extends any[] ? T : never
+type ElementOfArray<T> =
+  T extends ReadonlyArray<infer TElement> ? TElement : never
 
 interface PaginationData {
   has_next_page: boolean