@umituz/react-native-ai-groq-provider 1.0.0

package/src/infrastructure/telemetry/TelemetryHooks.ts

@@ -0,0 +1,79 @@
+/**
+ * Telemetry Hooks
+ * Simple telemetry tracking for Groq operations
+ */
+
+type TelemetryEvent = {
+  name: string;
+  timestamp: number;
+  data?: Record<string, unknown>;
+};
+
+class Telemetry {
+  private events: TelemetryEvent[] = [];
+  private enabled = __DEV__;
+
+  /**
+   * Log a telemetry event
+   */
+  log(name: string, data?: Record<string, unknown>): void {
+    if (!this.enabled) return;
+
+    const event: TelemetryEvent = {
+      name,
+      timestamp: Date.now(),
+      data,
+    };
+
+    this.events.push(event);
+
+    if (__DEV__) {
+      console.log(`[Groq Telemetry] ${name}`, data);
+    }
+  }
+
+  /**
+   * Get all events
+   */
+  getEvents(): TelemetryEvent[] {
+    return [...this.events];
+  }
+
+  /**
+   * Clear all events
+   */
+  clear(): void {
+    this.events = [];
+  }
+
+  /**
+   * Enable/disable telemetry
+   */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Check if telemetry is enabled
+   */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+}
+
+/**
+ * Singleton instance
+ */
+export const telemetry = new Telemetry();
+
+/**
+ * Hook to use telemetry in components
+ */
+export function useTelemetry() {
+  return {
+    log: telemetry.log.bind(telemetry),
+    getEvents: telemetry.getEvents.bind(telemetry),
+    clear: telemetry.clear.bind(telemetry),
+    isEnabled: telemetry.isEnabled.bind(telemetry),
+  };
+}

package/src/infrastructure/telemetry/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Telemetry
+ */
+
+export { telemetry, useTelemetry } from "./TelemetryHooks";

package/src/infrastructure/utils/async/execute-state.util.ts

@@ -0,0 +1,76 @@
+/**
+ * Async State Utilities
+ */
+
+/**
+ * State setters for async operations
+ */
+export interface AsyncStateSetters<T> {
+  setLoading: (loading: boolean) => void;
+  setError: (error: string | null) => void;
+  setData?: (data: T | null) => void;
+}
+
+/**
+ * Callbacks for async operations
+ */
+export interface AsyncCallbacks<T> {
+  onSuccess?: (data: T) => void;
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Execute async function with state management
+ */
+export async function executeWithState<T>(
+  setters: AsyncStateSetters<T>,
+  asyncFn: () => Promise<T>,
+  callbacks?: AsyncCallbacks<T>
+): Promise<T> {
+  const { setLoading, setError, setData } = setters;
+
+  try {
+    setLoading(true);
+    setError(null);
+
+    const result = await asyncFn();
+
+    setData?.(result);
+    callbacks?.onSuccess?.(result);
+
+    return result;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    setError(errorMessage);
+    callbacks?.onError?.(error as Error);
+    throw error;
+  } finally {
+    setLoading(false);
+  }
+}
+
+/**
+ * Execute async function with retry logic
+ */
+export async function executeWithRetry<T>(
+  asyncFn: () => Promise<T>,
+  maxRetries: number = 3,
+  delayMs: number = 1000
+): Promise<T> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await asyncFn();
+    } catch (error) {
+      lastError = error as Error;
+
+      if (attempt < maxRetries - 1) {
+        // Wait before retrying with exponential backoff
+        await new Promise((resolve) => setTimeout(resolve, delayMs * Math.pow(2, attempt)));
+      }
+    }
+  }
+
+  throw lastError;
+}

package/src/infrastructure/utils/async/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Async utilities
+ */
+
+export { executeWithState, executeWithRetry } from "./execute-state.util";
+export type { AsyncStateSetters, AsyncCallbacks } from "./execute-state.util";

package/src/infrastructure/utils/content-mapper.util.ts

@@ -0,0 +1,86 @@
+/**
+ * Content Mapper Utility
+ * Utilities for working with message content
+ */
+
+import type { GroqMessage } from "../../domain/entities";
+
+/**
+ * Create a user message
+ */
+export function createUserMessage(content: string): GroqMessage {
+  return {
+    role: "user",
+    content,
+  };
+}
+
+/**
+ * Create an assistant message
+ */
+export function createAssistantMessage(content: string): GroqMessage {
+  return {
+    role: "assistant",
+    content,
+  };
+}
+
+/**
+ * Create a system message
+ */
+export function createSystemMessage(content: string): GroqMessage {
+  return {
+    role: "system",
+    content,
+  };
+}
+
+/**
+ * Create a text message (defaults to user role)
+ */
+export function createTextMessage(content: string, role: "user" | "assistant" | "system" = "user"): GroqMessage {
+  return {
+    role,
+    content,
+  };
+}
+
+/**
+ * Convert a simple prompt string to an array of messages
+ */
+export function promptToMessages(prompt: string, systemPrompt?: string): GroqMessage[] {
+  const messages: GroqMessage[] = [];
+
+  if (systemPrompt) {
+    messages.push({
+      role: "system",
+      content: systemPrompt,
+    });
+  }
+
+  messages.push({
+    role: "user",
+    content: prompt,
+  });
+
+  return messages;
+}
+
+/**
+ * Extract text content from an array of messages
+ */
+export function extractTextFromMessages(messages: GroqMessage[]): string {
+  return messages.map((m) => `[${m.role}]: ${m.content}`).join("\n\n");
+}
+
+/**
+ * Format messages for display in UI
+ */
+export function formatMessagesForDisplay(messages: GroqMessage[]): string {
+  return messages
+    .map((m) => {
+      const role = m.role === "system" ? "System" : m.role === "user" ? "You" : "Assistant";
+      return `${role}:\n${m.content}`;
+    })
+    .join("\n\n---\n\n");
+}

package/src/infrastructure/utils/error-mapper.util.ts

@@ -0,0 +1,77 @@
+/**
+ * Error Mapper Utility
+ * Utilities for handling and mapping errors
+ */
+
+import { GroqError, GroqErrorType } from "../../domain/entities/error.types";
+
+/**
+ * Get user-friendly error message
+ */
+export function getUserFriendlyError(error: unknown): string {
+  if (error instanceof GroqError) {
+    switch (error.type) {
+      case GroqErrorType.INVALID_API_KEY:
+        return "Invalid API key. Please check your Groq API credentials.";
+      case GroqErrorType.MISSING_CONFIG:
+        return "Configuration missing. Please initialize the Groq provider.";
+      case GroqErrorType.NETWORK_ERROR:
+        return "Network error. Please check your internet connection.";
+      case GroqErrorType.ABORT_ERROR:
+        return "Request was cancelled.";
+      case GroqErrorType.RATE_LIMIT_ERROR:
+        return "Rate limit exceeded. Please wait a moment and try again.";
+      case GroqErrorType.QUOTA_EXCEEDED:
+        return "API quota exceeded. Please check your Groq account.";
+      case GroqErrorType.SERVER_ERROR:
+        return "Groq server error. Please try again later.";
+      default:
+        return error.message || "An unknown error occurred.";
+    }
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return "An unknown error occurred.";
+}
+
+/**
+ * Check if error is retryable
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (error instanceof GroqError) {
+    return (
+      error.type === GroqErrorType.RATE_LIMIT_ERROR ||
+      error.type === GroqErrorType.SERVER_ERROR ||
+      error.type === GroqErrorType.NETWORK_ERROR
+    );
+  }
+  return false;
+}
+
+/**
+ * Check if error is authentication related
+ */
+export function isAuthError(error: unknown): boolean {
+  if (error instanceof GroqError) {
+    return error.type === GroqErrorType.INVALID_API_KEY;
+  }
+  return false;
+}
+
+/**
+ * Format error for logging
+ */
+export function formatErrorForLogging(error: unknown): string {
+  if (error instanceof GroqError) {
+    return `[GroqError:${error.type}] ${error.message}`;
+  }
+
+  if (error instanceof Error) {
+    return `[${error.name}] ${error.message}`;
+  }
+
+  return String(error);
+}

package/src/infrastructure/utils/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Infrastructure Utilities
+ */
+
+export * from "./content-mapper.util";
+export * from "./error-mapper.util";
+export * from "./async";

package/src/presentation/hooks/useGroq.ts

@@ -0,0 +1,224 @@
+/**
+ * useGroq Hook
+ * Main React hook for Groq text generation
+ */
+
+import { useState, useCallback, useRef } from "react";
+import type { GroqGenerationConfig, GroqChatConfig } from "../../domain/entities";
+import { groqHttpClient } from "../../infrastructure/services/GroqClient";
+import { chatSessionService } from "../../infrastructure/services/ChatSession";
+import { textGeneration, chatGeneration } from "../../infrastructure/services/TextGeneration";
+import { structuredText } from "../../infrastructure/services/StructuredText";
+import { streaming } from "../../infrastructure/services/Streaming";
+import { getUserFriendlyError } from "../../infrastructure/utils/error-mapper.util";
+import { telemetry } from "../../infrastructure/telemetry";
+
+export interface UseGroqOptions {
+  /** Initial model to use */
+  model?: string;
+  /** Default generation config */
+  generationConfig?: GroqGenerationConfig;
+  /** Callback when generation starts */
+  onStart?: () => void;
+  /** Callback when generation completes */
+  onSuccess?: (result: string) => void;
+  /** Callback when generation fails */
+  onError?: (error: string) => void;
+}
+
+export interface UseGroqReturn {
+  /** Loading state */
+  isLoading: boolean;
+  /** Error message */
+  error: string | null;
+  /** Generated result */
+  result: string | null;
+  /** Generate text from a prompt */
+  generate: (prompt: string, options?: GroqGenerationConfig) => Promise<string>;
+  /** Generate structured JSON output */
+  generateJSON: <T = Record<string, unknown>>(
+    prompt: string,
+    options?: GroqGenerationConfig & { schema?: Record<string, unknown> }
+  ) => Promise<T>;
+  /** Stream text generation */
+  stream: (
+    prompt: string,
+    onChunk: (chunk: string) => void,
+    options?: GroqGenerationConfig
+  ) => Promise<void>;
+  /** Reset state */
+  reset: () => void;
+  /** Clear error */
+  clearError: () => void;
+}
+
+/**
+ * Hook for Groq text generation
+ */
+export function useGroq(options: UseGroqOptions = {}): UseGroqReturn {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [result, setResult] = useState<string | null>(null);
+  const abortControllerRef = useRef<AbortController | null>(null);
+
+  const generate = useCallback(
+    async (prompt: string, config?: GroqGenerationConfig): Promise<string> => {
+      // Cancel any ongoing request
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+
+      abortControllerRef.current = new AbortController();
+      setIsLoading(true);
+      setError(null);
+      setResult(null);
+
+      telemetry.log("groq_generate_start", { prompt: prompt.substring(0, 100) });
+      options.onStart?.();
+
+      try {
+        const response = await textGeneration(prompt, {
+          model: options.model,
+          generationConfig: { ...options.generationConfig, ...config },
+        });
+
+        setResult(response);
+        options.onSuccess?.(response);
+        telemetry.log("groq_generate_success", { responseLength: response.length });
+
+        return response;
+      } catch (err) {
+        const errorMessage = getUserFriendlyError(err);
+        setError(errorMessage);
+        options.onError?.(errorMessage);
+        telemetry.log("groq_generate_error", { error: errorMessage });
+        throw err;
+      } finally {
+        setIsLoading(false);
+        abortControllerRef.current = null;
+      }
+    },
+    [options]
+  );
+
+  const generateJSON = useCallback(
+    async <T = Record<string, unknown>,>(
+      prompt: string,
+      config?: GroqGenerationConfig & { schema?: Record<string, unknown> }
+    ): Promise<T> => {
+      // Cancel any ongoing request
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+
+      abortControllerRef.current = new AbortController();
+      setIsLoading(true);
+      setError(null);
+      setResult(null);
+
+      telemetry.log("groq_generate_json_start", { prompt: prompt.substring(0, 100) });
+      options.onStart?.();
+
+      try {
+        const response = await structuredText<T>(prompt, {
+          model: options.model,
+          generationConfig: { ...options.generationConfig, ...config },
+          schema: config?.schema,
+        });
+
+        setResult(JSON.stringify(response, null, 2));
+        options.onSuccess?.(JSON.stringify(response, null, 2));
+        telemetry.log("groq_generate_json_success");
+
+        return response;
+      } catch (err) {
+        const errorMessage = getUserFriendlyError(err);
+        setError(errorMessage);
+        options.onError?.(errorMessage);
+        telemetry.log("groq_generate_json_error", { error: errorMessage });
+        throw err;
+      } finally {
+        setIsLoading(false);
+        abortControllerRef.current = null;
+      }
+    },
+    [options]
+  );
+
+  const stream = useCallback(
+    async (
+      prompt: string,
+      onChunk: (chunk: string) => void,
+      config?: GroqGenerationConfig
+    ): Promise<void> => {
+      // Cancel any ongoing request
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+
+      abortControllerRef.current = new AbortController();
+      setIsLoading(true);
+      setError(null);
+      setResult(null);
+
+      let fullContent = "";
+
+      telemetry.log("groq_stream_start", { prompt: prompt.substring(0, 100) });
+      options.onStart?.();
+
+      try {
+        for await (const chunk of streaming(prompt, {
+          model: options.model,
+          generationConfig: { ...options.generationConfig, ...config },
+          callbacks: {
+            onChunk: (c) => {
+              fullContent += c;
+              onChunk(c);
+            },
+          },
+        })) {
+          // Streamed via callback
+        }
+
+        setResult(fullContent);
+        options.onSuccess?.(fullContent);
+        telemetry.log("groq_stream_success", { contentLength: fullContent.length });
+      } catch (err) {
+        const errorMessage = getUserFriendlyError(err);
+        setError(errorMessage);
+        options.onError?.(errorMessage);
+        telemetry.log("groq_stream_error", { error: errorMessage });
+        throw err;
+      } finally {
+        setIsLoading(false);
+        abortControllerRef.current = null;
+      }
+    },
+    [options]
+  );
+
+  const reset = useCallback(() => {
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort();
+      abortControllerRef.current = null;
+    }
+    setIsLoading(false);
+    setError(null);
+    setResult(null);
+  }, []);
+
+  const clearError = useCallback(() => {
+    setError(null);
+  }, []);
+
+  return {
+    isLoading,
+    error,
+    result,
+    generate,
+    generateJSON,
+    stream,
+    reset,
+    clearError,
+  };
+}

package/src/presentation/hooks/useOperationManager.ts

@@ -0,0 +1,110 @@
+/**
+ * useOperationManager Hook
+ * Manages async operations with loading, error, and success states
+ */
+
+import { useState, useCallback, useRef } from "react";
+import { getUserFriendlyError } from "../../infrastructure/utils/error-mapper.util";
+import { telemetry } from "../../infrastructure/telemetry";
+
+export interface OperationState<T> {
+  isLoading: boolean;
+  error: string | null;
+  data: T | null;
+}
+
+export interface UseOperationManagerOptions<T> {
+  /** Initial data */
+  initialData?: T | null;
+  /** Callback when operation starts */
+  onStart?: () => void;
+  /** Callback when operation succeeds */
+  onSuccess?: (data: T) => void;
+  /** Callback when operation fails */
+  onError?: (error: string) => void;
+}
+
+/**
+ * Hook for managing async operations
+ */
+export function useOperationManager<T = unknown>(
+  options: UseOperationManagerOptions<T> = {}
+) {
+  const [state, setState] = useState<OperationState<T>>({
+    isLoading: false,
+    error: null,
+    data: options.initialData ?? null,
+  });
+
+  const abortControllerRef = useRef<AbortController | null>(null);
+  const operationNameRef = useRef<string>("");
+
+  const execute = useCallback(
+    async <R = T,>(
+      operationName: string,
+      asyncFn: (signal?: AbortSignal) => Promise<R>,
+      config?: { abortPrevious?: boolean }
+    ): Promise<R> => {
+      // Cancel previous operation if configured
+      if (config?.abortPrevious && abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+
+      abortControllerRef.current = new AbortController();
+      operationNameRef.current = operationName;
+
+      setState((prev) => ({ ...prev, isLoading: true, error: null }));
+
+      telemetry.log(`${operationName}_start`);
+      options.onStart?.();
+
+      try {
+        const result = await asyncFn(abortControllerRef.current.signal);
+
+        setState((prev) => ({ ...prev, isLoading: false, data: result as unknown as T }));
+        options.onSuccess?.(result as unknown as T);
+        telemetry.log(`${operationName}_success`);
+
+        return result;
+      } catch (error) {
+        const errorMessage = getUserFriendlyError(error);
+        setState((prev) => ({ ...prev, isLoading: false, error: errorMessage }));
+        options.onError?.(errorMessage);
+        telemetry.log(`${operationName}_error`, { error: errorMessage });
+        throw error;
+      } finally {
+        abortControllerRef.current = null;
+      }
+    },
+    [options]
+  );
+
+  const reset = useCallback(() => {
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort();
+      abortControllerRef.current = null;
+    }
+    setState((prev) => ({
+      ...prev,
+      isLoading: false,
+      error: null,
+      data: options.initialData ?? null,
+    }));
+  }, [options.initialData]);
+
+  const clearError = useCallback(() => {
+    setState((prev) => ({ ...prev, error: null }));
+  }, []);
+
+  const setData = useCallback((data: T | null) => {
+    setState((prev) => ({ ...prev, data }));
+  }, []);
+
+  return {
+    ...state,
+    execute,
+    reset,
+    clearError,
+    setData,
+  };
+}