@alumbwe/anvil 1.0.0 → 1.0.1

package/src/utils/anvil-api.ts

@@ -1,612 +0,0 @@
-import { WEBSITE_URL } from '@anvil/sdk'
-import type {
-  PublishAgentsResponse,
-} from '@anvil/common/types/api/agents/publish'
-import type { FeedbackRequest } from '@anvil/common/schemas/feedback'
-
-/**
- * API response types for consistent error handling.
- *
- * When `ok` is true, `data` may be undefined for responses with no body (e.g., 204 No Content).
- * Callers should check for `response.data` when they expect data from the endpoint.
- */
-export type ApiResponse<T> =
-  | { ok: true; status: number; data?: T }
-  | { ok: false; status: number; error?: string; errorData?: Record<string, unknown> }
-
-// ============================================================================
-// Type-safe endpoint request/response types
-// ============================================================================
-
-/** User fields that can be fetched from /api/v1/me */
-export type UserField = 'id' | 'email' | 'discord_id'
-
-export type UserDetails<T extends UserField = UserField> = {
-  [K in T]: K extends 'discord_id' ? string | null : string
-}
-
-export interface UsageRequest {
-  fingerprintId?: string
-}
-
-export interface UsageResponse {
-  type: 'usage-response'
-  usage: number
-  remainingBalance: number | null
-  balanceBreakdown?: Record<string, number>
-  next_quota_reset: string | null
-}
-
-export interface LoginCodeRequest {
-  fingerprintId: string
-}
-
-export interface LoginCodeResponse {
-  loginUrl: string
-  fingerprintHash: string
-  expiresAt: string
-}
-
-export interface LoginStatusRequest {
-  fingerprintId: string
-  fingerprintHash: string
-  expiresAt: string
-}
-
-export interface LoginStatusResponse {
-  user?: Record<string, unknown>
-}
-
-export interface LogoutRequest {
-  userId?: string
-  fingerprintId?: string
-  fingerprintHash?: string
-}
-
-export interface FeedbackResponse {
-  success: boolean
-}
-
-/**
- * Retry configuration
- */
-export interface RetryConfig {
-  /** Maximum number of retry attempts (default: 3) */
-  maxRetries?: number
-  /** Initial delay in ms before first retry (default: 1000) */
-  initialDelayMs?: number
-  /** Maximum delay in ms between retries (default: 10000) */
-  maxDelayMs?: number
-  /** HTTP status codes to retry on (default: [408, 429, 500, 502, 503, 504]) */
-  retryableStatusCodes?: number[]
-}
-
-const DEFAULT_RETRY_CONFIG: Required<RetryConfig> = {
-  maxRetries: 3,
-  initialDelayMs: 1000,
-  maxDelayMs: 10000,
-  retryableStatusCodes: [408, 429, 500, 502, 503, 504],
-}
-
-/**
- * Configuration for creating a Anvil API client
- */
-export interface AnvilApiClientConfig {
-  /** Base URL for API requests (defaults to WEBSITE_URL from SDK) */
-  baseUrl?: string
-  /** Auth token for Bearer authentication */
-  authToken?: string
-  /** Custom fetch implementation (for testing) */
-  fetch?: typeof fetch
-  /** Default timeout in ms for all requests (default: 30000) */
-  defaultTimeoutMs?: number
-  /** Default retry configuration */
-  retry?: RetryConfig
-}
-
-/**
- * Options for individual requests
- */
-export interface RequestOptions {
-  /** Query parameters to append to URL */
-  query?: Record<string, string>
-  /** Include Authorization header (default: true when authToken is set) */
-  includeAuth?: boolean
-  /** Include session token as Cookie header (for legacy endpoints) */
-  includeCookie?: boolean
-  /** Request timeout in ms (overrides default) */
-  timeoutMs?: number
-  /** Retry configuration (overrides default) */
-  retry?: RetryConfig | false
-  /** Custom headers */
-  headers?: Record<string, string>
-}
-
-export interface AnvilApiClient {
-  readonly baseUrl: string
-  readonly authToken?: string
-
-  /** Make a raw HTTP request */
-  request<T>(
-    method: string,
-    path: string,
-    body?: unknown,
-    options?: RequestOptions,
-  ): Promise<ApiResponse<T>>
-
-  /** Make a GET request */
-  get<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>
-
-  /** Make a POST request */
-  post<T>(
-    path: string,
-    body?: Record<string, unknown>,
-    options?: RequestOptions,
-  ): Promise<ApiResponse<T>>
-
-  /** Make a PUT request */
-  put<T>(
-    path: string,
-    body?: Record<string, unknown>,
-    options?: RequestOptions,
-  ): Promise<ApiResponse<T>>
-
-  /** Make a PATCH request */
-  patch<T>(
-    path: string,
-    body?: Record<string, unknown>,
-    options?: RequestOptions,
-  ): Promise<ApiResponse<T>>
-
-  /** Make a DELETE request */
-  delete<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>
-
-  // ============================================================================
-  // Type-safe endpoint methods
-  // ============================================================================
-
-  /** Fetch user details from /api/v1/me */
-  me<T extends UserField>(
-    fields: readonly T[],
-  ): Promise<ApiResponse<UserDetails<T>>>
-
-  /** Fetch usage data from /api/v1/usage */
-  usage(req?: UsageRequest): Promise<ApiResponse<UsageResponse>>
-
-  /** Request a login code from /api/auth/cli/code */
-  loginCode(req: LoginCodeRequest): Promise<ApiResponse<LoginCodeResponse>>
-
-  /** Check login status from /api/auth/cli/status */
-  loginStatus(
-    req: LoginStatusRequest,
-  ): Promise<ApiResponse<LoginStatusResponse>>
-
-  /** Publish agents via /api/agents/publish */
-  publish(
-    data: Record<string, unknown>[],
-    allLocalAgentIds?: string[],
-  ): Promise<ApiResponse<PublishAgentsResponse>>
-
-  /** Logout via /api/auth/cli/logout */
-  logout(req?: LogoutRequest): Promise<ApiResponse<void>>
-
-  /** Submit feedback via /api/v1/feedback */
-  feedback(req: FeedbackRequest): Promise<ApiResponse<FeedbackResponse>>
-}
-
-const TLS_CERTIFICATE_ERROR_CODES = new Set([
-  'DEPTH_ZERO_SELF_SIGNED_CERT',
-  'SELF_SIGNED_CERT_IN_CHAIN',
-  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
-  'ERR_TLS_CERT_ALTNAME_INVALID',
-  'CERT_HAS_EXPIRED',
-])
-
-function getTlsCertificateError(error: Error, depth = 0): Error | null {
-  const code =
-    error &&
-    typeof error === 'object' &&
-    'code' in error &&
-    typeof error.code === 'string'
-      ? error.code
-      : undefined
-  const message = error.message.toLowerCase()
-  if (
-    (code && TLS_CERTIFICATE_ERROR_CODES.has(code)) ||
-    message.includes('self signed certificate') ||
-    message.includes('unable to verify the first certificate') ||
-    message.includes('certificate has expired') ||
-    message.includes('certificate verify failed')
-  ) {
-    return error
-  }
-
-  if (depth >= 2 || !(error.cause instanceof Error)) {
-    return null
-  }
-
-  return getTlsCertificateError(error.cause, depth + 1)
-}
-
-function formatNetworkErrorMessage(error: Error, method: string, url: string) {
-  const requestUrl = new URL(url)
-  const tlsCertificateError = getTlsCertificateError(error)
-
-  if (tlsCertificateError) {
-    return [
-      `TLS certificate verification failed for ${requestUrl.origin}.`,
-      'If your network intercepts HTTPS traffic, install its root certificate into your system trust store or use a network path that does not intercept TLS.',
-      `Original error: ${tlsCertificateError.message} (${method} ${url})`,
-    ].join(' ')
-  }
-
-  return `${error.message} (${method} ${url})`
-}
-
-/**
- * Sleep for a given duration
- */
-const sleep = (ms: number): Promise<void> =>
-  new Promise((resolve) => setTimeout(resolve, ms))
-
-/**
- * Calculate delay with exponential backoff and jitter
- */
-const calculateBackoffDelay = (
-  attempt: number,
-  initialDelayMs: number,
-  maxDelayMs: number,
-): number => {
-  const exponentialDelay = initialDelayMs * Math.pow(2, attempt)
-  const jitter = Math.random() * 0.3 * exponentialDelay // 0-30% jitter
-  return Math.min(exponentialDelay + jitter, maxDelayMs)
-}
-
-/**
- * Check if an error is retryable (network errors).
- *
- * Note: AbortError is NOT retryable because it indicates intentional cancellation
- * (e.g., user cancelled the request or our timeout was exceeded).
- */
-const isRetryableError = (error: unknown): boolean => {
-  if (error instanceof Error) {
-    const name = error.name.toLowerCase()
-    const message = error.message.toLowerCase()
-
-    // Don't retry abort errors - they indicate intentional cancellation
-    if (name === 'aborterror') {
-      return false
-    }
-    if (getTlsCertificateError(error)) {
-      return false
-    }
-
-    return (
-      name === 'timeouterror' ||
-      message.includes('network') ||
-      message.includes('fetch') ||
-      message.includes('econnreset') ||
-      message.includes('econnrefused')
-    )
-  }
-  return false
-}
-
-/**
- * Create a Anvil API client for making authenticated requests to the Anvil API
- */
-export function createAnvilApiClient(
-  config: AnvilApiClientConfig = {},
-): AnvilApiClient {
-  const {
-    baseUrl = WEBSITE_URL,
-    authToken,
-    fetch: fetchFn = fetch,
-    defaultTimeoutMs = 30000,
-    retry: defaultRetryConfig = {},
-  } = config
-
-  const mergedDefaultRetry: Required<RetryConfig> = {
-    ...DEFAULT_RETRY_CONFIG,
-    ...defaultRetryConfig,
-  }
-
-  async function request<T>(
-    method: string,
-    path: string,
-    body?: unknown,
-    options: RequestOptions = {},
-  ): Promise<ApiResponse<T>> {
-    const {
-      query,
-      includeAuth = true,
-      includeCookie = false,
-      timeoutMs = defaultTimeoutMs,
-      retry: retryConfig = mergedDefaultRetry,
-      headers: customHeaders = {},
-    } = options
-
-    // Build URL with query parameters
-    let url = `${baseUrl}${path}`
-    if (query && Object.keys(query).length > 0) {
-      const params = new URLSearchParams(query)
-      url += `?${params.toString()}`
-    }
-
-    // Build headers
-    const headers: Record<string, string> = { ...customHeaders }
-    if (authToken && includeAuth) {
-      headers['Authorization'] = `Bearer ${authToken}`
-    }
-    if (authToken && includeCookie) {
-      headers['Cookie'] = `next-auth.session-token=${authToken};`
-    }
-    if (body !== undefined) {
-      headers['Content-Type'] = 'application/json'
-    }
-
-    // Build fetch options
-    const fetchOptions: RequestInit = {
-      method,
-      headers,
-    }
-    if (body !== undefined) {
-      fetchOptions.body = JSON.stringify(body)
-    }
-
-    // Determine retry config
-    const shouldRetry = retryConfig !== false
-    const retryOpts = shouldRetry
-      ? { ...mergedDefaultRetry, ...retryConfig }
-      : null
-
-    let lastError: unknown
-    const maxAttempts = shouldRetry ? (retryOpts?.maxRetries ?? 0) + 1 : 1
-
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-      // Create abort controller for timeout
-      const controller = new AbortController()
-      const timeoutId = setTimeout(() => controller.abort(), timeoutMs)
-
-      try {
-        const response = await fetchFn(url, {
-          ...fetchOptions,
-          signal: controller.signal,
-        })
-
-        clearTimeout(timeoutId)
-
-        if (response.ok) {
-          try {
-            const responseBody = await response.json()
-            const data = responseBody as T
-            return { ok: true, status: response.status, data }
-          } catch {
-            // Response was OK but no JSON body (e.g., 204 No Content)
-            return { ok: true, status: response.status }
-          }
-        }
-
-        // Check if we should retry on this status code
-        if (
-          shouldRetry &&
-          retryOpts &&
-          retryOpts.retryableStatusCodes.includes(response.status) &&
-          attempt < maxAttempts - 1
-        ) {
-          const delay = calculateBackoffDelay(
-            attempt,
-            retryOpts.initialDelayMs,
-            retryOpts.maxDelayMs,
-          )
-          await sleep(delay)
-          continue
-        }
-
-        // Parse error response
-        let errorMessage: string | undefined
-        let errorData: unknown
-        try {
-          const errorBody = await response.json()
-          errorData = errorBody
-          errorMessage =
-            errorBody?.error || errorBody?.message || response.statusText
-        } catch {
-          try {
-            errorMessage = await response.text()
-          } catch {
-            errorMessage = response.statusText
-          }
-        }
-
-        return { ok: false, status: response.status, error: errorMessage, errorData: errorData as Record<string, unknown> | undefined }
-      } catch (error) {
-        clearTimeout(timeoutId)
-        lastError = error
-
-        // Check if we should retry on this error
-        if (
-          shouldRetry &&
-          retryOpts &&
-          isRetryableError(error) &&
-          attempt < maxAttempts - 1
-        ) {
-          const delay = calculateBackoffDelay(
-            attempt,
-            retryOpts.initialDelayMs,
-            retryOpts.maxDelayMs,
-          )
-          await sleep(delay)
-          continue
-        }
-
-        // Don't retry, throw the error with URL context
-        if (error instanceof Error) {
-          const enhancedError = new Error(
-            formatNetworkErrorMessage(error, method, url),
-          )
-          enhancedError.name = error.name
-          enhancedError.cause = error
-          throw enhancedError
-        }
-        throw error
-      }
-    }
-
-    // Should not reach here, but just in case
-    throw lastError ?? new Error('Request failed after all retries')
-  }
-
-  return {
-    baseUrl,
-    authToken,
-    request,
-
-    get<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>> {
-      return request<T>('GET', path, undefined, options)
-    },
-
-    post<T>(
-      path: string,
-      body?: Record<string, unknown>,
-      options?: RequestOptions,
-    ): Promise<ApiResponse<T>> {
-      return request<T>('POST', path, body, options)
-    },
-
-    put<T>(
-      path: string,
-      body?: Record<string, unknown>,
-      options?: RequestOptions,
-    ): Promise<ApiResponse<T>> {
-      return request<T>('PUT', path, body, options)
-    },
-
-    patch<T>(
-      path: string,
-      body?: Record<string, unknown>,
-      options?: RequestOptions,
-    ): Promise<ApiResponse<T>> {
-      return request<T>('PATCH', path, body, options)
-    },
-
-    delete<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>> {
-      return request<T>('DELETE', path, undefined, options)
-    },
-
-    // ============================================================================
-    // Type-safe endpoint methods
-    // ============================================================================
-
-    me<T extends UserField>(
-      fields: readonly T[],
-    ): Promise<ApiResponse<UserDetails<T>>> {
-      return request<UserDetails<T>>('GET', '/api/v1/me', undefined, {
-        query: { fields: fields.join(',') },
-      })
-    },
-
-    usage(req: UsageRequest = {}): Promise<ApiResponse<UsageResponse>> {
-      // Auth is sent via Authorization header (includeAuth defaults to true)
-      return request<UsageResponse>('POST', '/api/v1/usage', {
-        fingerprintId: req.fingerprintId ?? 'cli-usage',
-      })
-    },
-
-    loginCode(req: LoginCodeRequest): Promise<ApiResponse<LoginCodeResponse>> {
-      return request<LoginCodeResponse>(
-        'POST',
-        '/api/auth/cli/code',
-        { fingerprintId: req.fingerprintId },
-        { includeAuth: false },
-      )
-    },
-
-    loginStatus(
-      req: LoginStatusRequest,
-    ): Promise<ApiResponse<LoginStatusResponse>> {
-      return request<LoginStatusResponse>('GET', '/api/auth/cli/status', undefined, {
-        query: {
-          fingerprintId: req.fingerprintId,
-          fingerprintHash: req.fingerprintHash,
-          expiresAt: req.expiresAt,
-        },
-        includeAuth: false,
-      })
-    },
-
-    publish(
-      data: Record<string, unknown>[],
-      allLocalAgentIds?: string[],
-    ): Promise<ApiResponse<PublishAgentsResponse>> {
-      // Auth is sent via Authorization header (includeAuth defaults to true)
-      return request<PublishAgentsResponse>('POST', '/api/agents/publish', {
-        data,
-        allLocalAgentIds,
-      })
-    },
-
-    logout(req: LogoutRequest = {}): Promise<ApiResponse<void>> {
-      // Auth is sent via Authorization header (includeAuth defaults to true)
-      return request<void>('POST', '/api/auth/cli/logout', {
-        userId: req.userId,
-        fingerprintId: req.fingerprintId,
-        fingerprintHash: req.fingerprintHash,
-      })
-    },
-
-    feedback(req: FeedbackRequest): Promise<ApiResponse<FeedbackResponse>> {
-      return request<FeedbackResponse>('POST', '/api/v1/feedback', req, {
-        // Feedback submissions are not idempotent server-side yet, so avoid automatic retries.
-        retry: false,
-      })
-    },
-  }
-}
-
-// ============================================================================
-// Shared singleton client
-// ============================================================================
-
-let sharedClient: AnvilApiClient | null = null
-let sharedAuthToken: string | undefined
-// Track the token that was used to create the current client instance
-let clientCreatedWithToken: string | undefined
-
-/**
- * Get or create the shared API client singleton.
- * The client is lazily created and reused across the application.
- *
- * Note: Always call setApiClientAuthToken() before getApiClient() when you need
- * to ensure a specific auth token is used. The client is recreated whenever
- * the auth token changes.
- */
-export function getApiClient(): AnvilApiClient {
-  // Recreate client if it doesn't exist or if the token has changed since creation
-  if (!sharedClient || clientCreatedWithToken !== sharedAuthToken) {
-    sharedClient = createAnvilApiClient({ authToken: sharedAuthToken })
-    clientCreatedWithToken = sharedAuthToken
-  }
-  return sharedClient
-}
-
-/**
- * Set the auth token for the shared API client.
- * This will cause the next call to getApiClient() to create a new client
- * with the updated token.
- */
-export function setApiClientAuthToken(authToken: string | undefined): void {
-  sharedAuthToken = authToken
-  // Note: We don't eagerly invalidate the client here. Instead, getApiClient()
-  // checks if the token has changed and recreates the client if needed.
-  // This avoids race conditions where the client is nullified but not yet recreated.
-}
-
-/**
- * Reset the shared client (mainly for testing)
- */
-export function resetApiClient(): void {
-  sharedClient = null
-  sharedAuthToken = undefined
-  clientCreatedWithToken = undefined
-}