feat: base api-client impl (#4694)

* feat: base api-client impl * fix: doc * feat: start work on module stuff * feat: migrate v2/v3 projects into module system * fix: lint & README.md contributing * refactor: remove utils old api client prototype * fix: lint * fix: api url issues * fix: baseurl in error.vue * fix: readme * fix typo in readme * Update apps/frontend/src/providers/api-client.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Calum H. <hendersoncal117@gmail.com> * Update packages/api-client/src/features/verbose-logging.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Calum H. <hendersoncal117@gmail.com> * Update packages/api-client/src/features/retry.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Calum H. <hendersoncal117@gmail.com> --------- Signed-off-by: Calum H. <hendersoncal117@gmail.com> Co-authored-by: Prospector <6166773+Prospector@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2025-11-12 20:29:12 +00:00
parent 590ba3ce55
commit 70e2138248
45 changed files with 3155 additions and 123 deletions
--- a/packages/api-client/src/platform/generic.ts
+++ b/packages/api-client/src/platform/generic.ts
@@ -0,0 +1,51 @@
+import { $fetch, FetchError } from 'ofetch'
+
+import { AbstractModrinthClient } from '../core/abstract-client'
+import type { ModrinthApiError } from '../core/errors'
+import type { RequestOptions } from '../types/request'
+
+/**
+ * Generic platform client using ofetch
+ *
+ * This client works in any JavaScript environment (Node.js, browser, workers).
+ *
+ * @example
+ * ```typescript
+ * const client = new GenericModrinthClient({
+ *   userAgent: 'my-app/1.0.0',
+ *   features: [
+ *     new AuthFeature({ token: 'mrp_...' }),
+ *     new RetryFeature({ maxAttempts: 3 })
+ *   ]
+ * })
+ *
+ * const project = await client.request('/project/sodium', { api: 'labrinth', version: 2 })
+ * ```
+ */
+export class GenericModrinthClient extends AbstractModrinthClient {
+	protected async executeRequest<T>(url: string, options: RequestOptions): Promise<T> {
+		try {
+			const response = await $fetch<T>(url, {
+				method: options.method ?? 'GET',
+				headers: options.headers,
+				body: options.body as BodyInit,
+				params: options.params as Record<string, string>,
+				timeout: options.timeout,
+				signal: options.signal,
+			})
+
+			return response
+		} catch (error) {
+			// ofetch throws FetchError for HTTP errors
+			throw this.normalizeError(error)
+		}
+	}
+
+	protected normalizeError(error: unknown): ModrinthApiError {
+		if (error instanceof FetchError) {
+			return this.createNormalizedError(error, error.response?.status, error.data)
+		}
+
+		return super.normalizeError(error)
+	}
+}
--- a/packages/api-client/src/platform/nuxt.ts
+++ b/packages/api-client/src/platform/nuxt.ts
@@ -0,0 +1,113 @@
+import { FetchError } from 'ofetch'
+
+import { AbstractModrinthClient } from '../core/abstract-client'
+import type { ModrinthApiError } from '../core/errors'
+import type { CircuitBreakerState, CircuitBreakerStorage } from '../features/circuit-breaker'
+import type { ClientConfig } from '../types/client'
+import type { RequestOptions } from '../types/request'
+
+/**
+ * Circuit breaker storage using Nuxt's useState
+ *
+ * This provides cross-request persistence in SSR while also working in client-side.
+ * State is shared between requests in the same Nuxt context.
+ */
+export class NuxtCircuitBreakerStorage implements CircuitBreakerStorage {
+	private getState(): Map<string, CircuitBreakerState> {
+		// @ts-expect-error - useState is provided by Nuxt runtime
+		const state = useState<Map<string, CircuitBreakerState>>(
+			'circuit-breaker-state',
+			() => new Map(),
+		)
+		return state.value
+	}
+
+	get(key: string): CircuitBreakerState | undefined {
+		return this.getState().get(key)
+	}
+
+	set(key: string, state: CircuitBreakerState): void {
+		this.getState().set(key, state)
+	}
+
+	clear(key: string): void {
+		this.getState().delete(key)
+	}
+}
+
+/**
+ * Nuxt-specific configuration
+ */
+export interface NuxtClientConfig extends ClientConfig {
+	// TODO: do we want to provide this for tauri+base as well? its not used on app
+	/**
+	 * Rate limit key for server-side requests
+	 * This is injected as x-ratelimit-key header on server-side
+	 */
+	rateLimitKey?: string
+}
+
+/**
+ * Nuxt platform client using Nuxt's $fetch
+ *
+ * This client is optimized for Nuxt applications and handles SSR/CSR automatically.
+ *
+ * @example
+ * ```typescript
+ * // In a Nuxt composable
+ * const config = useRuntimeConfig()
+ * const auth = await useAuth()
+ *
+ * const client = new NuxtModrinthClient({
+ *   userAgent: 'my-nuxt-app/1.0.0',
+ *   rateLimitKey: import.meta.server ? config.rateLimitKey : undefined,
+ *   features: [
+ *     new AuthFeature({ token: () => auth.value.token })
+ *   ]
+ * })
+ *
+ * const project = await client.request('/project/sodium', { api: 'labrinth', version: 2 })
+ * ```
+ */
+export class NuxtModrinthClient extends AbstractModrinthClient {
+	protected declare config: NuxtClientConfig
+
+	protected async executeRequest<T>(url: string, options: RequestOptions): Promise<T> {
+		try {
+			// @ts-expect-error - $fetch is provided by Nuxt runtime
+			const response = await $fetch<T>(url, {
+				method: options.method ?? 'GET',
+				headers: options.headers,
+				body: options.body,
+				params: options.params,
+				timeout: options.timeout,
+				signal: options.signal,
+			})
+
+			return response
+		} catch (error) {
+			throw this.normalizeError(error)
+		}
+	}
+
+	protected normalizeError(error: unknown): ModrinthApiError {
+		if (error instanceof FetchError) {
+			return this.createNormalizedError(error, error.response?.status, error.data)
+		}
+
+		return super.normalizeError(error)
+	}
+
+	protected buildDefaultHeaders(): Record<string, string> {
+		const headers: Record<string, string> = {
+			...super.buildDefaultHeaders(),
+		}
+
+		// @ts-expect-error - import.meta is provided by Nuxt
+		if (import.meta.server && this.config.rateLimitKey) {
+			headers['x-ratelimit-key'] = this.config.rateLimitKey
+		}
+
+		return headers
+	}
+}
--- a/packages/api-client/src/platform/tauri.ts
+++ b/packages/api-client/src/platform/tauri.ts
@@ -0,0 +1,102 @@
+import { AbstractModrinthClient } from '../core/abstract-client'
+import type { ModrinthApiError } from '../core/errors'
+import type { ClientConfig } from '../types/client'
+import type { RequestOptions } from '../types/request'
+
+/**
+ * Tauri-specific configuration
+ * TODO: extend into interface if needed.
+ */
+export type TauriClientConfig = ClientConfig
+
+/**
+ * Extended error type with HTTP response metadata
+ */
+interface HttpError extends Error {
+	statusCode?: number
+	responseData?: unknown
+}
+
+/**
+ * Tauri platform client using Tauri v2 HTTP plugin
+
+ * @example
+ * ```typescript
+ * import { getVersion } from '@tauri-apps/api/app'
+ *
+ * const version = await getVersion()
+ * const client = new TauriModrinthClient({
+ *   userAgent: `modrinth/theseus/${version} (support@modrinth.com)`,
+ *   features: [
+ *     new AuthFeature({ token: 'mrp_...' })
+ *   ]
+ * })
+ *
+ * const project = await client.request('/project/sodium', { api: 'labrinth', version: 2 })
+ * ```
+ */
+export class TauriModrinthClient extends AbstractModrinthClient {
+	protected declare config: TauriClientConfig
+
+	protected async executeRequest<T>(url: string, options: RequestOptions): Promise<T> {
+		try {
+			// Dynamically import Tauri HTTP plugin
+			// This allows the package to be used in non-Tauri environments
+			const { fetch: tauriFetch } = await import('@tauri-apps/plugin-http')
+
+			let body: BodyInit | null | undefined = undefined
+			if (options.body) {
+				if (typeof options.body === 'object' && !(options.body instanceof FormData)) {
+					body = JSON.stringify(options.body)
+				} else {
+					body = options.body as BodyInit
+				}
+			}
+
+			let fullUrl = url
+			if (options.params) {
+				const queryParams = new URLSearchParams(options.params as Record<string, string>).toString()
+				fullUrl = `${url}?${queryParams}`
+			}
+
+			const response = await tauriFetch(fullUrl, {
+				method: options.method ?? 'GET',
+				headers: options.headers,
+				body,
+			})
+
+			if (!response.ok) {
+				let responseData: unknown
+				try {
+					responseData = await response.json()
+				} catch {
+					responseData = undefined
+				}
+
+				const error = new Error(`HTTP ${response.status}: ${response.statusText}`) as HttpError
+
+				error.statusCode = response.status
+				error.responseData = responseData
+
+				throw error
+			}
+
+			const data = await response.json()
+			return data as T
+		} catch (error) {
+			throw this.normalizeError(error)
+		}
+	}
+
+	protected normalizeError(error: unknown): ModrinthApiError {
+		if (error instanceof Error) {
+			const httpError = error as HttpError
+			const statusCode = httpError.statusCode
+			const responseData = httpError.responseData
+
+			return this.createNormalizedError(error, statusCode, responseData)
+		}
+
+		return super.normalizeError(error)
+	}
+}