@umituz/web-ai-groq-provider 1.0.1

package/src/infrastructure/services/http-client.service.ts

@@ -0,0 +1,246 @@
+/**
+ * Groq HTTP Client Service
+ * @description Handles all HTTP communication with Groq API
+ */
+
+import type { IGroqHttpClient } from "../../domain/interfaces";
+import type { GroqConfig, GroqChatRequest, GroqChatResponse, GroqChatChunk } from "../../domain/entities";
+import { GroqError } from "../utils/groq-error.util";
+import { GroqErrorType, mapHttpStatusToErrorType } from "../constants/error.constants";
+import { DEFAULT_BASE_URL, TIMEOUTS } from "../constants/groq.constants";
+
+const isDevelopment = typeof process !== "undefined" && process.env?.NODE_ENV === "development";
+
+class GroqHttpClientService implements IGroqHttpClient {
+  private config: GroqConfig | null = null;
+  private initialized = false;
+
+  initialize(config: GroqConfig): void {
+    const apiKey = config.apiKey?.trim();
+
+    if (isDevelopment) {
+      console.log("[GroqClient] Initializing:", {
+        hasApiKey: !!apiKey,
+        keyLength: apiKey?.length,
+        keyPrefix: apiKey ? `${apiKey.substring(0, 10)}...` : "",
+        baseUrl: config.baseUrl || DEFAULT_BASE_URL,
+        timeoutMs: config.timeoutMs || TIMEOUTS.DEFAULT,
+        textModel: config.textModel,
+      });
+    }
+
+    if (!apiKey || apiKey.length < 10) {
+      throw new GroqError(
+        GroqErrorType.INVALID_API_KEY,
+        "API key is required and must be at least 10 characters"
+      );
+    }
+
+    this.config = {
+      apiKey,
+      baseUrl: config.baseUrl || DEFAULT_BASE_URL,
+      timeoutMs: config.timeoutMs || TIMEOUTS.DEFAULT,
+      textModel: config.textModel,
+    };
+    this.initialized = true;
+
+    if (isDevelopment) {
+      console.log("[GroqClient] Initialization complete:", {
+        initialized: this.initialized,
+        baseUrl: this.config.baseUrl,
+      });
+    }
+  }
+
+  isInitialized(): boolean {
+    return this.initialized && this.config !== null;
+  }
+
+  getApiKey(): string {
+    if (!this.config) {
+      throw new GroqError(
+        GroqErrorType.MISSING_CONFIG,
+        "Client not initialized"
+      );
+    }
+    return this.config.apiKey;
+  }
+
+  setApiKey(apiKey: string): void {
+    if (!this.config) {
+      throw new GroqError(
+        GroqErrorType.MISSING_CONFIG,
+        "Client not initialized. Call initialize() first."
+      );
+    }
+    this.config = { ...this.config, apiKey: apiKey.trim() };
+  }
+
+  async postChatCompletion(request: GroqChatRequest): Promise<GroqChatResponse> {
+    return this.request<GroqChatResponse>("/chat/completions", {
+      ...request,
+      stream: false,
+    });
+  }
+
+  async streamChatCompletion(request: GroqChatRequest): Promise<ReadableStream> {
+    if (!this.config || !this.initialized) {
+      throw new GroqError(
+        GroqErrorType.MISSING_CONFIG,
+        "Client not initialized. Call initialize() first."
+      );
+    }
+
+    const url = `${this.config.baseUrl}/chat/completions`;
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.apiKey}`,
+      },
+      body: JSON.stringify({ ...request, stream: true }),
+    });
+
+    if (!response.ok) {
+      throw new GroqError(
+        mapHttpStatusToErrorType(response.status),
+        `HTTP ${response.status}: ${response.statusText}`,
+        undefined,
+        { status: response.status, url: response.url }
+      );
+    }
+
+    if (!response.body) {
+      throw new GroqError(
+        GroqErrorType.NETWORK_ERROR,
+        "Response body is null"
+      );
+    }
+
+    return response.body;
+  }
+
+  private async request<T>(
+    endpoint: string,
+    body: unknown,
+    signal?: AbortSignal
+  ): Promise<T> {
+    if (!this.config || !this.initialized) {
+      throw new GroqError(
+        GroqErrorType.MISSING_CONFIG,
+        "Client not initialized. Call initialize() first."
+      );
+    }
+
+    const url = `${this.config.baseUrl}${endpoint}`;
+    const timeout = this.config.timeoutMs || TIMEOUTS.DEFAULT;
+
+    if (isDevelopment) {
+      console.log("[GroqClient] API Request:", {
+        url,
+        endpoint,
+        method: "POST",
+        timeout: `${timeout}ms`,
+        hasBody: !!body,
+      });
+    }
+
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      if (signal) {
+        signal.addEventListener("abort", () => controller.abort());
+      }
+
+      const fetchStartTime = Date.now();
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      const fetchDuration = Date.now() - fetchStartTime;
+      clearTimeout(timeoutId);
+
+      if (isDevelopment) {
+        console.log("[GroqClient] API Response:", {
+          status: response.status,
+          ok: response.ok,
+          fetchDuration: `${fetchDuration}ms`,
+        });
+      }
+
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+
+      return (await response.json()) as T;
+    } catch (error) {
+      throw this.handleRequestError(error);
+    }
+  }
+
+  private async handleErrorResponse(response: Response): Promise<never> {
+    let errorMessage = `HTTP ${response.status}`;
+    const errorType = mapHttpStatusToErrorType(response.status);
+
+    try {
+      const errorData = (await response.json()) as {
+        error?: { message?: string };
+      };
+      if (errorData.error?.message) {
+        errorMessage = errorData.error.message;
+      }
+    } catch {
+      // If parsing fails, use default message
+    }
+
+    throw new GroqError(errorType, errorMessage, undefined, {
+      status: response.status,
+      url: response.url,
+    });
+  }
+
+  private handleRequestError(error: unknown): GroqError {
+    if (error instanceof GroqError) {
+      return error;
+    }
+
+    if (error instanceof Error) {
+      if (error.name === "AbortError") {
+        return new GroqError(
+          GroqErrorType.ABORT_ERROR,
+          "Request was aborted by the client",
+          error
+        );
+      }
+
+      if (error.name === "TypeError" && error.message.includes("network")) {
+        return new GroqError(
+          GroqErrorType.NETWORK_ERROR,
+          "Network error: Unable to connect to Groq API",
+          error
+        );
+      }
+    }
+
+    return new GroqError(
+      GroqErrorType.UNKNOWN_ERROR,
+      error instanceof Error ? error.message : "Unknown error occurred",
+      error as Error
+    );
+  }
+
+  reset(): void {
+    this.config = null;
+    this.initialized = false;
+  }
+}
+
+export const groqHttpClient = new GroqHttpClientService();

package/src/infrastructure/services/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Infrastructure Services Index
+ * Subpath: @umituz/web-ai-groq-provider/services
+ */
+
+export { groqHttpClient } from "./http-client.service";
+export { textGenerationService } from "./text-generation.service";
+export type { IGroqHttpClient } from "../../domain/interfaces";
+export type { IGroqChatService } from "../../domain/interfaces";

package/src/infrastructure/services/text-generation.service.ts

@@ -0,0 +1,221 @@
+/**
+ * Text Generation Service
+ * @description Handles text generation using Groq API
+ */
+
+import type { IGroqChatService } from "../../domain/interfaces";
+import type {
+  GroqMessage,
+  GroqChatRequest,
+  TextGenerationOptions,
+  StreamingCallbacks,
+  StructuredGenerationOptions,
+} from "../../domain/interfaces";
+import { groqHttpClient } from "./http-client.service";
+import { GroqError } from "../utils/groq-error.util";
+import { GroqErrorType } from "../constants/error.constants";
+import { DEFAULT_MODELS, API_ENDPOINTS, DEFAULT_GENERATION_CONFIG } from "../constants/groq.constants";
+
+const isDevelopment = typeof process !== "undefined" && process.env?.NODE_ENV === "development";
+
+class TextGenerationService implements IGroqChatService {
+  async generateCompletion(
+    prompt: string,
+    options: TextGenerationOptions = {}
+  ): Promise<string> {
+    const startTime = Date.now();
+    const model = options.model || DEFAULT_MODELS.TEXT;
+
+    if (isDevelopment) {
+      console.log("[Groq] generateCompletion called:", {
+        model,
+        promptLength: prompt.length,
+      });
+    }
+
+    const messages: GroqMessage[] = [{ role: "user", content: prompt }];
+    const request = this.buildRequest(model, messages, options.generationConfig);
+
+    const response = await groqHttpClient.postChatCompletion(request);
+    const content = response.choices[0]?.message?.content;
+
+    if (!content) {
+      throw new GroqError(
+        GroqErrorType.UNKNOWN_ERROR,
+        "No content generated from Groq API"
+      );
+    }
+
+    if (isDevelopment) {
+      console.log("[Groq] generateCompletion complete:", {
+        duration: `${Date.now() - startTime}ms`,
+        responseLength: content.length,
+      });
+    }
+
+    return content;
+  }
+
+  async generateChatCompletion(
+    messages: GroqMessage[],
+    options: TextGenerationOptions = {}
+  ): Promise<string> {
+    const startTime = Date.now();
+    const model = options.model || DEFAULT_MODELS.TEXT;
+
+    if (isDevelopment) {
+      console.log("[Groq] generateChatCompletion called:", {
+        model,
+        messageCount: messages.length,
+      });
+    }
+
+    const request = this.buildRequest(model, messages, options.generationConfig);
+    const response = await groqHttpClient.postChatCompletion(request);
+    const content = response.choices[0]?.message?.content;
+
+    if (!content) {
+      throw new GroqError(
+        GroqErrorType.UNKNOWN_ERROR,
+        "No content generated from Groq API"
+      );
+    }
+
+    if (isDevelopment) {
+      console.log("[Groq] generateChatCompletion complete:", {
+        duration: `${Date.now() - startTime}ms`,
+        responseLength: content.length,
+      });
+    }
+
+    return content;
+  }
+
+  async generateStructured<T>(
+    prompt: string,
+    options: StructuredGenerationOptions<T> = {}
+  ): Promise<T> {
+    const startTime = Date.now();
+    const model = options.model || DEFAULT_MODELS.TEXT;
+
+    if (isDevelopment) {
+      console.log("[Groq] generateStructured called:", {
+        model,
+        promptLength: prompt.length,
+        hasSchema: !!options.schema,
+      });
+    }
+
+    // Build JSON prompt
+    const jsonPrompt = this.buildStructuredPrompt(prompt, options.schema);
+    const messages: GroqMessage[] = [{ role: "user", content: jsonPrompt }];
+    const request = this.buildRequest(model, messages, {
+      ...options.generationConfig,
+      temperature: 0.1, // Lower temperature for structured output
+    });
+
+    const response = await groqHttpClient.postChatCompletion(request);
+    const content = response.choices[0]?.message?.content;
+
+    if (!content) {
+      throw new GroqError(
+        GroqErrorType.UNKNOWN_ERROR,
+        "No content generated from Groq API"
+      );
+    }
+
+    // Parse JSON response
+    try {
+      const jsonMatch = content.match(/```json\n([\s\S]*?)\n```/) ||
+                      content.match(/\{[\s\S]*\}/);
+      const jsonStr = jsonMatch ? jsonMatch[1] || jsonMatch[0] : content;
+      const parsed = JSON.parse(jsonStr) as T;
+
+      if (isDevelopment) {
+        console.log("[Groq] generateStructured complete:", {
+          duration: `${Date.now() - startTime}ms`,
+        });
+      }
+
+      return parsed;
+    } catch (error) {
+      throw new GroqError(
+        GroqErrorType.UNKNOWN_ERROR,
+        "Failed to parse structured response as JSON",
+        error as Error
+      );
+    }
+  }
+
+  async *streamCompletion(
+    prompt: string,
+    callbacks: StreamingCallbacks,
+    options: TextGenerationOptions = {}
+  ): AsyncGenerator<void, void, unknown> {
+    const startTime = Date.now();
+    const model = options.model || DEFAULT_MODELS.TEXT;
+    const messages: GroqMessage[] = [{ role: "user", content: prompt }];
+    const request = this.buildRequest(model, messages, options.generationConfig);
+
+    if (isDevelopment) {
+      console.log("[Groq] streamCompletion called:", { model });
+    }
+
+    try {
+      const response = await groqHttpClient.postChatCompletion({
+        ...request,
+        stream: true,
+      });
+
+      // Note: The actual streaming implementation would need to be handled
+      // by the streamChatCompletion method returning a ReadableStream
+      // This is a simplified version
+      callbacks.onComplete?.(response.choices[0]?.message?.content || "");
+    } catch (error) {
+      callbacks.onError?.(error as Error);
+      throw error;
+    }
+
+    if (isDevelopment) {
+      console.log("[Groq] streamCompletion complete:", {
+        duration: `${Date.now() - startTime}ms`,
+      });
+    }
+  }
+
+  private buildRequest(
+    model: string,
+    messages: GroqMessage[],
+    config?: TextGenerationOptions["generationConfig"]
+  ): GroqChatRequest {
+    return {
+      model,
+      messages,
+      temperature: config?.temperature ?? DEFAULT_GENERATION_CONFIG.temperature,
+      max_tokens: config?.maxTokens ?? DEFAULT_GENERATION_CONFIG.maxTokens,
+      top_p: config?.topP ?? DEFAULT_GENERATION_CONFIG.topP,
+      n: config?.n,
+      stop: config?.stop,
+      frequency_penalty: config?.frequencyPenalty,
+      presence_penalty: config?.presencePenalty,
+    };
+  }
+
+  private buildStructuredPrompt(
+    prompt: string,
+    schema?: Record<string, unknown>
+  ): string {
+    let structuredPrompt = `Please generate a JSON response for the following request.\n\n`;
+
+    if (schema) {
+      structuredPrompt += `Expected JSON schema:\n${JSON.stringify(schema, null, 2)}\n\n`;
+    }
+
+    structuredPrompt += `Request:\n${prompt}\n\n`;
+    structuredPrompt += `Respond only with valid JSON, formatted as:\n\`\`\`json\n{...}\n\`\`\``;
+
+    return structuredPrompt;
+  }
+}
+
+export const textGenerationService = new TextGenerationService();

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

@@ -0,0 +1,72 @@
+/**
+ * Error Utilities
+ * @description Helper functions for error handling
+ */
+
+import type { GroqMessage } from "../../domain/entities";
+import { GroqErrorType } from "../constants/error.constants";
+
+/**
+ * Get user-friendly error message
+ */
+export function getUserFriendlyError(error: Error): string {
+  const errorMessage = error.message.toLowerCase();
+
+  if (errorMessage.includes("api key") || errorMessage.includes("unauthorized")) {
+    return "Please check your Groq API key and try again.";
+  }
+
+  if (errorMessage.includes("rate limit")) {
+    return "You've reached the rate limit. Please wait a moment and try again.";
+  }
+
+  if (errorMessage.includes("network") || errorMessage.includes("fetch")) {
+    return "Network error. Please check your connection and try again.";
+  }
+
+  if (errorMessage.includes("abort")) {
+    return "Request was cancelled.";
+  }
+
+  return error.message || "An unexpected error occurred. Please try again.";
+}
+
+/**
+ * Check if error is retryable
+ */
+export function isRetryableError(errorType: GroqErrorType): boolean {
+  return [
+    GroqErrorType.NETWORK_ERROR,
+    GroqErrorType.RATE_LIMIT_ERROR,
+    GroqErrorType.SERVER_ERROR,
+  ].includes(errorType);
+}
+
+/**
+ * Check if error is auth-related
+ */
+export function isAuthError(errorType: GroqErrorType): boolean {
+  return errorType === GroqErrorType.INVALID_API_KEY;
+}
+
+/**
+ * Format error for logging
+ */
+export function formatErrorForLogging(error: unknown): {
+  message: string;
+  type: string;
+  stack?: string;
+} {
+  if (error instanceof Error) {
+    return {
+      message: error.message,
+      type: error.name,
+      stack: error.stack,
+    };
+  }
+
+  return {
+    message: String(error),
+    type: typeof error,
+  };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Groq Error Class
+ * @description Custom error for Groq API operations
+ */
+
+import { GroqErrorType } from "../constants/error.constants";
+
+export class GroqError extends Error {
+  constructor(
+    public readonly type: GroqErrorType,
+    message: string,
+    public readonly cause?: Error,
+    public readonly metadata?: { readonly status?: number; readonly url?: string }
+  ) {
+    super(message);
+    this.name = "GroqError";
+  }
+}

package/src/infrastructure/utils/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Infrastructure Utils Index
+ * Subpath: @umituz/web-ai-groq-provider/services
+ */
+
+export {
+  createUserMessage,
+  createAssistantMessage,
+  createSystemMessage,
+  createTextMessage,
+  promptToMessages,
+  extractTextFromMessages,
+  formatMessagesForDisplay,
+} from "./message.util";
+
+export {
+  getUserFriendlyError,
+  isRetryableError,
+  isAuthError,
+  formatErrorForLogging,
+} from "./error.util";
+
+export { GroqError } from "./groq-error.util";

package/src/infrastructure/utils/message.util.ts

@@ -0,0 +1,57 @@
+/**
+ * Message Utilities
+ * @description Helper functions for creating and working with messages
+ */
+
+import type { GroqMessage, GroqMessageRole } 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 with specified role
+ */
+export function createTextMessage(role: GroqMessageRole, content: string): GroqMessage {
+  return { role, content };
+}
+
+/**
+ * Convert a simple prompt to message array
+ */
+export function promptToMessages(prompt: string): GroqMessage[] {
+  return [{ role: "user", content: prompt }];
+}
+
+/**
+ * Extract text content from messages
+ */
+export function extractTextFromMessages(messages: GroqMessage[]): string {
+  return messages.map(m => m.content).join("\n\n");
+}
+
+/**
+ * Format messages for display
+ */
+export function formatMessagesForDisplay(messages: GroqMessage[]): string {
+  return messages
+    .map(m => `[${m.role.toUpperCase()}]: ${m.content}`)
+    .join("\n\n---\n\n");
+}

package/src/presentation/hooks/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Presentation Hooks Index
+ * Subpath: @umituz/web-ai-groq-provider/hooks
+ */
+
+export { useGroq } from "./use-groq.hook";
+export type { UseGroqOptions, UseGroqReturn } from "./use-groq.hook";