@alumbwe/anvil 1.0.0

package/src/hooks/use-usage-query.ts

@@ -0,0 +1,124 @@
+import { env } from '@anvil/common/env'
+import { useCallback } from 'react'
+
+import { invalidateActivityQuery, useActivityQuery } from './use-activity-query'
+import { getAuthToken } from '../utils/auth'
+import { logger as defaultLogger } from '../utils/logger'
+
+import type { ClientEnv } from '@anvil/common/types/contracts/env'
+import type { Logger } from '@anvil/common/types/contracts/logger'
+
+// Query keys for type-safe cache management
+export const usageQueryKeys = {
+  all: ['usage'] as const,
+  current: () => [...usageQueryKeys.all, 'current'] as const,
+}
+
+interface UsageResponse {
+  type: 'usage-response'
+  usage: number
+  remainingBalance: number | null
+  balanceBreakdown?: {
+    free: number
+    paid: number
+    ad?: number
+    referral?: number
+    admin?: number
+  }
+  next_quota_reset: string | null
+  autoTopupEnabled?: boolean
+}
+
+interface FetchUsageParams {
+  authToken: string
+  logger?: Logger
+  clientEnv?: ClientEnv
+}
+
+/**
+ * Fetches usage data from the API
+ */
+export async function fetchUsageData({
+  authToken,
+  logger = defaultLogger,
+  clientEnv = env,
+}: FetchUsageParams): Promise<UsageResponse> {
+  const appUrl = clientEnv.NEXT_PUBLIC_ANVIL_APP_URL
+  if (!appUrl) {
+    throw new Error('NEXT_PUBLIC_ANVIL_APP_URL is not set')
+  }
+
+  const response = await fetch(`${appUrl}/api/v1/usage`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      fingerprintId: 'cli-usage',
+      authToken,
+    }),
+  })
+
+  if (!response.ok) {
+    logger.error(
+      { status: response.status },
+      'Failed to fetch usage data from API',
+    )
+    throw new Error(`Failed to fetch usage: ${response.status}`)
+  }
+
+  const responseBody = await response.json()
+  const data = responseBody as UsageResponse
+  return data
+}
+
+export interface UseUsageQueryDeps {
+  logger?: Logger
+  enabled?: boolean
+  refetchInterval?: number | false
+  /** Refetch stale data when user becomes active after being idle */
+  refetchOnActivity?: boolean
+  /** Pause polling when user is idle */
+  pauseWhenIdle?: boolean
+  /** Time in ms to consider user idle (default: 30 seconds) */
+  idleThreshold?: number
+}
+
+/**
+ * Hook to fetch usage data from the API
+ * Uses the activity-aware query hook for terminal-specific optimizations
+ */
+export function useUsageQuery(deps: UseUsageQueryDeps = {}) {
+  const {
+    logger = defaultLogger,
+    enabled = true,
+    refetchInterval = false,
+    refetchOnActivity = false,
+    pauseWhenIdle = true,
+    idleThreshold = 30_000,
+  } = deps
+  const authToken = getAuthToken()
+
+  return useActivityQuery({
+    queryKey: usageQueryKeys.current(),
+    queryFn: () => fetchUsageData({ authToken: authToken!, logger }),
+    enabled: enabled && !!authToken,
+    staleTime: 0, // Always consider data stale for immediate refetching
+    gcTime: 5 * 60 * 1000, // 5 minutes
+    retry: false, // Don't retry failed usage queries
+    refetchOnMount: 'always', // Always refetch on mount to get fresh data when banner opens
+    refetchInterval, // Poll at specified interval (when banner is visible)
+    refetchOnActivity,
+    pauseWhenIdle,
+    idleThreshold,
+  })
+}
+
+/**
+ * Hook to manually trigger a usage data refresh
+ */
+export function useRefreshUsage() {
+  return useCallback(() => {
+    invalidateActivityQuery(usageQueryKeys.current())
+  }, [])
+}

package/src/hooks/use-user-details-query.ts

@@ -0,0 +1,93 @@
+import { useQuery } from '@tanstack/react-query'
+
+import { getAuthToken } from '../utils/auth'
+import { getApiClient, setApiClientAuthToken } from '../utils/anvil-api'
+import { logger as defaultLogger } from '../utils/logger'
+
+import type {
+  AnvilApiClient,
+  UserField,
+  UserDetails,
+} from '../utils/anvil-api'
+import type { Logger } from '@anvil/common/types/contracts/logger'
+
+// Re-export types for backwards compatibility
+export type { UserField, UserDetails }
+
+// Query keys for type-safe cache management
+export const userDetailsQueryKeys = {
+  all: ['userDetails'] as const,
+  fields: (fields: readonly UserField[]) =>
+    [...userDetailsQueryKeys.all, ...fields] as const,
+}
+
+interface FetchUserDetailsParams<T extends UserField> {
+  authToken: string
+  fields: readonly T[]
+  logger?: Logger
+  apiClient?: AnvilApiClient
+}
+
+/**
+ * Fetches specific user details from the /api/v1/me endpoint
+ */
+export async function fetchUserDetails<T extends UserField>({
+  authToken,
+  fields,
+  logger = defaultLogger,
+  apiClient: providedApiClient,
+}: FetchUserDetailsParams<T>): Promise<UserDetails<T> | null> {
+  let apiClient: AnvilApiClient
+  if (providedApiClient) {
+    apiClient = providedApiClient
+  } else {
+    setApiClientAuthToken(authToken)
+    apiClient = getApiClient()
+  }
+
+  const response = await apiClient.me(fields)
+
+  if (!response.ok) {
+    logger.error(
+      { status: response.status, fields },
+      'Failed to fetch user details from /api/v1/me',
+    )
+    throw new Error(`Failed to fetch user details (HTTP ${response.status})`)
+  }
+
+  return response.data ?? null
+}
+
+export interface UseUserDetailsQueryDeps<T extends UserField> {
+  fields: readonly T[]
+  logger?: Logger
+  enabled?: boolean
+}
+
+/**
+ * Hook to fetch specific user details
+ */
+export function useUserDetailsQuery<T extends UserField>({
+  fields,
+  logger = defaultLogger,
+  enabled = true,
+}: UseUserDetailsQueryDeps<T>) {
+  const authToken = getAuthToken()
+
+  return useQuery({
+    queryKey: userDetailsQueryKeys.fields(fields),
+    queryFn: async () => {
+      if (!authToken) {
+        throw new Error('No auth token available')
+      }
+      return fetchUserDetails({ authToken, fields, logger })
+    },
+    enabled: enabled && !!authToken,
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    gcTime: 30 * 60 * 1000, // 30 minutes
+    retry: false,
+    refetchOnMount: false,
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: false,
+  })
+}

package/src/hooks/use-why-did-you-update.ts

@@ -0,0 +1,177 @@
+import { useEffect, useRef } from 'react'
+
+import { getCliEnv } from '../utils/env'
+import { logger } from '../utils/logger'
+
+/**
+ * Hook to debug component rerenders by logging which props changed
+ * Based on the debugging pattern from MessageBlock component
+ *
+ * @param componentName - Name of the component for logging
+ * @param props - Props object to track changes for
+ * @param options - Optional configuration
+ * @param options.logLevel - Log level to use (default: 'info')
+ * @param options.enabled - Whether to enable logging (default: true in development)
+ *
+ * @example
+ * function MyComponent(props: MyProps) {
+ *   useWhyDidYouUpdate('MyComponent', props)
+ *   return <div>...</div>
+ * }
+ *
+ * @example
+ * function MyComponent(props: MyProps) {
+ *   useWhyDidYouUpdate('MyComponent', props, {
+ *     logLevel: 'debug',
+ *     enabled: getCliEnv().NODE_ENV === 'development'
+ *   })
+ *   return <div>...</div>
+ * }
+ */
+export function useWhyDidYouUpdate<T extends Record<string, any>>(
+  componentName: string,
+  props: T,
+  options: {
+    logLevel?: 'debug' | 'info' | 'warn' | 'error'
+    enabled?: boolean
+  } = {},
+): void {
+  const env = getCliEnv()
+  const {
+    logLevel = 'info',
+    enabled = env.NODE_ENV === 'development',
+  } = options
+
+  const previousProps = useRef<T | null>(null)
+  const renderCount = useRef(0)
+
+  useEffect(() => {
+    if (!enabled) return
+
+    renderCount.current += 1
+
+    if (previousProps.current) {
+      const propKeys = Object.keys(props) as (keyof T)[]
+      const changedProps = propKeys.filter(
+        (key) => previousProps.current![key] !== props[key],
+      )
+
+      if (changedProps.length > 0) {
+        const logData = {
+          renderCount: renderCount.current,
+          changedProps: changedProps.map((key) => String(key)),
+          propChanges: changedProps.reduce(
+            (acc, key) => {
+              acc[String(key)] = {
+                previous: previousProps.current![key],
+                current: props[key],
+              }
+              return acc
+            },
+            {} as Record<string, { previous: any; current: any }>,
+          ),
+        }
+
+        logger[logLevel](
+          logData,
+          `${componentName} render #${renderCount.current}: ${changedProps.length} ${changedProps.length === 1 ? 'prop' : 'props'} changed`,
+        )
+      } else {
+        logger[logLevel](
+          { renderCount: renderCount.current },
+          `${componentName} render #${renderCount.current}: No props changed (possible internal state or context change)`,
+        )
+      }
+    } else {
+      logger[logLevel](
+        { renderCount: renderCount.current },
+        `${componentName} initial render`,
+      )
+    }
+
+    previousProps.current = props
+  })
+}
+
+/**
+ * Hook variant that tracks rerenders by a unique identifier (like message ID)
+ * Maintains separate render counts for each unique ID
+ *
+ * @param componentName - Name of the component for logging
+ * @param id - Unique identifier for this instance
+ * @param props - Props object to track changes for
+ * @param options - Optional configuration
+ *
+ * @example
+ * function MessageBlock({ messageId, ...props }: MessageBlockProps) {
+ *   useWhyDidYouUpdateById('MessageBlock', messageId, props)
+ *   return <div>...</div>
+ * }
+ */
+export function useWhyDidYouUpdateById<T extends Record<string, any>>(
+  componentName: string,
+  id: string,
+  props: T,
+  options: {
+    logLevel?: 'debug' | 'info' | 'warn' | 'error'
+    enabled?: boolean
+  } = {},
+): void {
+  const env = getCliEnv()
+  const { logLevel = 'info', enabled = env.NODE_ENV === 'development' } =
+    options
+
+  const previousProps = useRef<T | null>(null)
+  const renderCountById = useRef<Record<string, number>>({})
+
+  useEffect(() => {
+    if (!enabled) return
+
+    renderCountById.current[id] = (renderCountById.current[id] || 0) + 1
+    const renderCount = renderCountById.current[id]
+
+    if (previousProps.current) {
+      const propKeys = Object.keys(props) as (keyof T)[]
+      const changedProps = propKeys.filter(
+        (key) => previousProps.current![key] !== props[key],
+      )
+
+      const logData = {
+        id,
+        renderCount,
+        changedProps: changedProps.map((key) => String(key)),
+      }
+
+      if (changedProps.length > 0) {
+        logger[logLevel](
+          {
+            ...logData,
+            propChanges: changedProps.reduce(
+              (acc, key) => {
+                acc[String(key)] = {
+                  previous: previousProps.current![key],
+                  current: props[key],
+                }
+                return acc
+              },
+              {} as Record<string, { previous: any; current: any }>,
+            ),
+          },
+          `${componentName} render #${renderCount} [${id}]: ${changedProps.length} ${changedProps.length === 1 ? 'prop' : 'props'} changed`,
+        )
+      } else {
+        logger[logLevel](
+          logData,
+          `${componentName} render #${renderCount} [${id}]: No props changed`,
+        )
+      }
+    } else {
+      logger[logLevel](
+        { id, renderCount },
+        `${componentName}[${id}] initial render`,
+      )
+    }
+
+    previousProps.current = props
+  })
+}