feat: add custom fetch support and refactor to named parameters (#46)

Co-authored-by: Claude <[email protected]>

Author: scottlovegrove

.github/workflows/validate-docs.yml

@@ -0,0 +1,47 @@
+name: Validate Documentation
+
+on:
+    pull_request:
+        paths:
+            - 'src/**'
+            - 'website/**'
+            - 'package*.json'
+            - '.nvmrc'
+
+jobs:
+    validate-docs:
+        runs-on: ubuntu-latest
+        timeout-minutes: 15
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version-file: .nvmrc
+
+            - name: Install SDK dependencies
+              run: npm ci
+
+            - name: Install docusaurus dependencies
+              working-directory: ./website
+              run: npm ci
+
+            - name: Build documentation
+              working-directory: ./website
+              run: npm run build
+
+            - name: Validate documentation build
+              run: |
+                  if [ ! -d "website/build" ]; then
+                      echo "❌ Documentation build failed - no build directory found"
+                      exit 1
+                  fi
+
+                  if [ ! -f "website/build/index.html" ]; then
+                      echo "❌ Documentation build failed - no index.html found"
+                      exit 1
+                  fi
+
+                  echo "✅ Documentation build successful"

src/authentication.ts

@@ -1,6 +1,14 @@
 import { v4 as uuid } from 'uuid'
 import { isSuccess, request } from './rest-client'
 import { TwistRequestError } from './types/errors'
+import type { CustomFetch } from './types/http'
+
+export type AuthOptions = {
+    /** Optional custom base URL for OAuth endpoints */
+    baseUrl?: string
+    /** Optional custom fetch implementation for cross-platform compatibility */
+    customFetch?: CustomFetch
+}
 
 /**
  * OAuth scopes for the Twist API.
@@ -140,9 +148,11 @@ export function getAuthorizationUrl(
 
 export async function getAuthToken(
     args: AuthTokenRequestArgs,
-    baseUrl?: string,
+    options?: AuthOptions,
 ): Promise<AuthTokenResponse> {
-    const tokenUrl = baseUrl ? `${baseUrl}/oauth/token` : 'https://twist.com/oauth/token'
+    const tokenUrl = options?.baseUrl
+        ? `${options.baseUrl}/oauth/token`
+        : 'https://twist.com/oauth/token'
 
     const payload = {
         clientId: args.clientId,
@@ -152,7 +162,13 @@ export async function getAuthToken(
         ...(args.redirectUri && { redirectUri: args.redirectUri }),
     }
 
-    const response = await request<AuthTokenResponse>('POST', tokenUrl, '', undefined, payload)
+    const response = await request<AuthTokenResponse>({
+        httpMethod: 'POST',
+        baseUri: tokenUrl,
+        relativePath: '',
+        payload,
+        customFetch: options?.customFetch,
+    })
 
     if (!isSuccess(response) || !response.data?.accessToken) {
         throw new TwistRequestError(
@@ -167,14 +183,22 @@ export async function getAuthToken(
 
 export async function revokeAuthToken(
     args: RevokeAuthTokenRequestArgs,
-    baseUrl?: string,
+    options?: AuthOptions,
 ): Promise<boolean> {
-    const revokeUrl = baseUrl ? `${baseUrl}/oauth/revoke` : 'https://twist.com/oauth/revoke'
-
-    const response = await request('POST', revokeUrl, '', undefined, {
-        clientId: args.clientId,
-        clientSecret: args.clientSecret,
-        token: args.accessToken,
+    const revokeUrl = options?.baseUrl
+        ? `${options.baseUrl}/oauth/revoke`
+        : 'https://twist.com/oauth/revoke'
+
+    const response = await request({
+        httpMethod: 'POST',
+        baseUri: revokeUrl,
+        relativePath: '',
+        payload: {
+            clientId: args.clientId,
+            clientSecret: args.clientSecret,
+            token: args.accessToken,
+        },
+        customFetch: options?.customFetch,
     })
 
     return isSuccess(response)

src/batch-builder.ts

@@ -1,11 +1,11 @@
 import { BaseClient } from './clients/base-client'
+import { fetchWithRetry } from './rest-client'
 import type {
     BatchApiResponse,
     BatchRequestDescriptor,
     BatchResponse,
     BatchResponseArray,
 } from './types/batch'
-import { TwistRequestError } from './types/errors'
 import { camelCaseKeys, snakeCaseKeys } from './utils/case-conversion'
 import { transformTimestamps } from './utils/timestamp-conversion'
 
@@ -98,26 +98,20 @@ export class BatchBuilder extends BaseClient {
             formData.append('parallel', 'true')
         }
 
-        // Execute the batch request
-        const response = await fetch(`${this.getBaseUri()}batch`, {
+        // Execute the batch request using fetchWithRetry for consistency and retry logic
+        const url = `${this.getBaseUri()}batch`
+        const options: RequestInit = {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/x-www-form-urlencoded',
                 Authorization: `Bearer ${this.apiToken}`,
             },
             body: formData.toString(),
-        })
-
-        if (!response.ok) {
-            const errorText = await response.text()
-            throw new TwistRequestError(
-                `Batch request failed with status ${response.status}`,
-                response.status,
-                errorText,
-            )
         }
 
-        const batchApiResponses: BatchApiResponse[] = await response.json()
+        const response = await fetchWithRetry<BatchApiResponse[]>(url, options, 3, this.customFetch)
+
+        const batchApiResponses = response.data
 
         // Process each response
         return batchApiResponses.map((apiResponse, index) => {

src/clients/base-client.ts

@@ -1,5 +1,6 @@
 import { getTwistBaseUri } from '../consts/endpoints'
 import type { ApiVersion } from '../types/api-version'
+import type { CustomFetch } from '../types/http'
 
 export type ClientConfig = {
     /** API token for authentication */
@@ -8,6 +9,8 @@ export type ClientConfig = {
     baseUrl?: string
     /** Optional API version. Defaults to 'v3' */
     version?: ApiVersion
+    /** Optional custom fetch implementation for cross-platform compatibility */
+    customFetch?: CustomFetch
 }
 
 /**
@@ -18,11 +21,13 @@ export class BaseClient {
     protected readonly apiToken: string
     protected readonly baseUrl?: string
     protected readonly defaultVersion: ApiVersion
+    protected readonly customFetch?: CustomFetch
 
     constructor(config: ClientConfig) {
         this.apiToken = config.apiToken
         this.baseUrl = config.baseUrl
         this.defaultVersion = config.version || 'v3'
+        this.customFetch = config.customFetch
     }
 
     /**