@vertz/fetch 0.1.0

package/README.md

@@ -0,0 +1,475 @@
+# @vertz/fetch
+
+Type-safe HTTP client for Vertz with automatic retries, streaming support, and flexible authentication strategies.
+
+## Features
+
+- **Type-safe requests** — Full TypeScript inference for request/response types
+- **Automatic retries** — Exponential/linear backoff with configurable retry logic
+- **Streaming support** — Server-Sent Events (SSE) and newline-delimited JSON (NDJSON)
+- **Flexible authentication** — Bearer tokens, Basic auth, API keys, or custom strategies
+- **Request/response hooks** — Intercept and transform at every stage
+- **Error handling** — Typed error classes for all HTTP status codes
+- **Timeout management** — Automatic timeout with AbortSignal support
+
+## Installation
+
+```bash
+npm install @vertz/fetch
+```
+
+## Quick Start
+
+```typescript
+import { FetchClient } from '@vertz/fetch';
+
+// Create a client with base configuration
+const client = new FetchClient({
+  baseURL: 'https://api.example.com',
+  headers: {
+    'User-Agent': 'MyApp/1.0',
+  },
+  timeoutMs: 5000,
+});
+
+// Make a typed GET request
+const response = await client.request<{ id: number; name: string }>('GET', '/users/1');
+console.log(response.data.name); // Fully typed!
+
+// POST with body
+const newUser = await client.request<{ id: number }>('POST', '/users', {
+  body: { name: 'Alice', email: 'alice@example.com' },
+});
+
+// Query parameters
+const users = await client.request<{ users: Array<{ id: number }> }>('GET', '/users', {
+  query: { page: 1, limit: 10 },
+});
+```
+
+## API Reference
+
+### `FetchClient`
+
+The main client class for making HTTP requests.
+
+#### Constructor
+
+```typescript
+new FetchClient(config: FetchClientConfig)
+```
+
+**Config options:**
+
+```typescript
+interface FetchClientConfig {
+  /** Base URL for all requests (e.g., 'https://api.example.com') */
+  baseURL?: string;
+  
+  /** Default headers added to every request */
+  headers?: Record<string, string>;
+  
+  /** Request timeout in milliseconds */
+  timeoutMs?: number;
+  
+  /** Retry configuration */
+  retry?: {
+    retries: number;
+    strategy: 'exponential' | 'linear' | ((attempt: number, baseBackoff: number) => number);
+    backoffMs: number;
+    retryOn: number[]; // Status codes to retry (default: [429, 500, 502, 503, 504])
+    retryOnError?: (error: Error) => boolean;
+  };
+  
+  /** Lifecycle hooks */
+  hooks?: {
+    beforeRequest?: (request: Request) => void | Promise<void>;
+    afterResponse?: (response: Response) => void | Promise<void>;
+    onError?: (error: Error) => void | Promise<void>;
+    beforeRetry?: (attempt: number, error: Error) => void | Promise<void>;
+    onStreamStart?: () => void;
+    onStreamChunk?: (chunk: unknown) => void;
+    onStreamEnd?: () => void;
+  };
+  
+  /** Authentication strategies (applied in order) */
+  authStrategies?: AuthStrategy[];
+  
+  /** Custom fetch implementation (default: globalThis.fetch) */
+  fetch?: typeof fetch;
+  
+  /** Credentials mode */
+  credentials?: RequestCredentials;
+}
+```
+
+#### Methods
+
+##### `request<T>(method, path, options?)`
+
+Make a standard HTTP request with JSON response.
+
+```typescript
+const response = await client.request<User>('GET', '/users/1');
+const { data, status, headers } = response;
+```
+
+**Options:**
+
+```typescript
+interface RequestOptions {
+  headers?: Record<string, string>;
+  query?: Record<string, unknown>;
+  body?: unknown; // Automatically JSON-stringified
+  signal?: AbortSignal;
+}
+```
+
+**Returns:**
+
+```typescript
+interface FetchResponse<T> {
+  data: T;
+  status: number;
+  headers: Headers;
+}
+```
+
+##### `requestStream<T>(options)`
+
+Stream responses using SSE or NDJSON format.
+
+```typescript
+for await (const chunk of client.requestStream<LogEntry>({
+  method: 'POST',
+  path: '/logs/stream',
+  format: 'sse', // or 'ndjson'
+  body: { query: 'error' },
+})) {
+  console.log(chunk); // Typed as LogEntry
+}
+```
+
+**Options:**
+
+```typescript
+interface StreamingRequestOptions {
+  method: string;
+  path: string;
+  format: 'sse' | 'ndjson';
+  headers?: Record<string, string>;
+  query?: Record<string, unknown>;
+  body?: unknown;
+  signal?: AbortSignal;
+}
+```
+
+### Authentication Strategies
+
+Configure one or more authentication strategies. They're applied in order.
+
+#### Bearer Token
+
+```typescript
+const client = new FetchClient({
+  baseURL: 'https://api.example.com',
+  authStrategies: [
+    {
+      type: 'bearer',
+      token: 'your-access-token',
+    },
+  ],
+});
+
+// Or with async token retrieval
+const client = new FetchClient({
+  authStrategies: [
+    {
+      type: 'bearer',
+      token: async () => await getAccessToken(),
+    },
+  ],
+});
+```
+
+#### Basic Auth
+
+```typescript
+const client = new FetchClient({
+  authStrategies: [
+    {
+      type: 'basic',
+      username: 'user',
+      password: 'pass',
+    },
+  ],
+});
+```
+
+#### API Key
+
+```typescript
+const client = new FetchClient({
+  authStrategies: [
+    {
+      type: 'apiKey',
+      key: 'your-api-key',
+      location: 'header', // or 'query'
+      name: 'X-API-Key', // Header name or query param name
+    },
+  ],
+});
+```
+
+#### Custom Strategy
+
+```typescript
+const client = new FetchClient({
+  authStrategies: [
+    {
+      type: 'custom',
+      apply: async (request) => {
+        // Modify the request (e.g., add custom headers)
+        request.headers.set('X-Custom-Auth', await getCustomToken());
+        return request;
+      },
+    },
+  ],
+});
+```
+
+### Error Handling
+
+All non-2xx responses throw typed error classes:
+
+```typescript
+import {
+  BadRequestError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  GoneError,
+  UnprocessableEntityError,
+  RateLimitError,
+  InternalServerError,
+  ServiceUnavailableError,
+  FetchError, // Base class
+} from '@vertz/fetch';
+
+try {
+  await client.request('GET', '/users/999');
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.error('User not found:', error.statusText);
+    console.error('Response body:', error.body);
+  } else if (error instanceof RateLimitError) {
+    console.error('Rate limited, retry after:', error.statusText);
+  }
+  throw error;
+}
+```
+
+All error classes extend `FetchError` with these properties:
+
+```typescript
+class FetchError extends Error {
+  status: number;
+  statusText: string;
+  body?: unknown; // Parsed response body (if available)
+}
+```
+
+### Retry Configuration
+
+Automatic retries with exponential backoff:
+
+```typescript
+const client = new FetchClient({
+  baseURL: 'https://api.example.com',
+  retry: {
+    retries: 3, // Retry up to 3 times
+    strategy: 'exponential', // 100ms, 200ms, 400ms, ...
+    backoffMs: 100, // Base delay
+    retryOn: [429, 500, 502, 503, 504], // Status codes to retry
+  },
+  hooks: {
+    beforeRetry: (attempt, error) => {
+      console.log(`Retry attempt ${attempt} after error:`, error.message);
+    },
+  },
+});
+```
+
+Custom backoff strategy:
+
+```typescript
+const client = new FetchClient({
+  retry: {
+    retries: 5,
+    strategy: (attempt, baseBackoff) => {
+      // Custom: jittered exponential backoff
+      const exponential = baseBackoff * 2 ** (attempt - 1);
+      const jitter = Math.random() * 0.3 * exponential;
+      return exponential + jitter;
+    },
+    backoffMs: 100,
+    retryOn: [429, 500, 502, 503, 504],
+  },
+});
+```
+
+### Request Lifecycle Hooks
+
+Intercept requests and responses at every stage:
+
+```typescript
+const client = new FetchClient({
+  baseURL: 'https://api.example.com',
+  hooks: {
+    beforeRequest: async (request) => {
+      console.log('Sending:', request.method, request.url);
+    },
+    afterResponse: async (response) => {
+      console.log('Received:', response.status);
+    },
+    onError: async (error) => {
+      console.error('Request failed:', error.message);
+      // Send to error tracking service
+      await sendToSentry(error);
+    },
+    beforeRetry: async (attempt, error) => {
+      console.log(`Retry ${attempt} after:`, error.message);
+    },
+  },
+});
+```
+
+### Streaming Hooks
+
+Monitor streaming responses:
+
+```typescript
+const client = new FetchClient({
+  hooks: {
+    onStreamStart: () => console.log('Stream started'),
+    onStreamChunk: (chunk) => console.log('Received chunk:', chunk),
+    onStreamEnd: () => console.log('Stream ended'),
+  },
+});
+
+for await (const event of client.requestStream({ 
+  method: 'GET', 
+  path: '/events', 
+  format: 'sse' 
+})) {
+  // Process event
+}
+```
+
+## Integration with @vertz/schema
+
+Use `@vertz/schema` for runtime validation of request/response data:
+
+```typescript
+import { FetchClient } from '@vertz/fetch';
+import { s } from '@vertz/schema';
+
+// Define schemas
+const UserSchema = s.object({
+  id: s.number(),
+  name: s.string(),
+  email: s.email(),
+  createdAt: s.string().datetime(),
+});
+
+const client = new FetchClient({
+  baseURL: 'https://api.example.com',
+  hooks: {
+    afterResponse: async (response) => {
+      // Validate responses in development
+      if (process.env.NODE_ENV === 'development') {
+        const data = await response.clone().json();
+        try {
+          UserSchema.parse(data);
+        } catch (error) {
+          console.error('Response validation failed:', error);
+        }
+      }
+    },
+  },
+});
+
+// Type-safe request with schema validation
+const response = await client.request<typeof UserSchema._output>('GET', '/users/1');
+
+// Or validate explicitly
+const data = await client.request<unknown>('GET', '/users/1');
+const user = UserSchema.parse(data.data); // Throws if invalid
+```
+
+## Advanced Examples
+
+### Timeout and Cancellation
+
+```typescript
+const controller = new AbortController();
+
+// Cancel after 3 seconds
+setTimeout(() => controller.abort(), 3000);
+
+try {
+  const response = await client.request('GET', '/slow-endpoint', {
+    signal: controller.signal,
+  });
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.error('Request cancelled');
+  }
+}
+```
+
+### Multiple Auth Strategies
+
+Apply multiple strategies in sequence (e.g., API key + Bearer token):
+
+```typescript
+const client = new FetchClient({
+  authStrategies: [
+    { type: 'apiKey', key: 'api-key', location: 'header', name: 'X-API-Key' },
+    { type: 'bearer', token: async () => await getAccessToken() },
+  ],
+});
+
+// Both headers will be set:
+// X-API-Key: api-key
+// Authorization: Bearer <token>
+```
+
+### Custom Fetch Implementation
+
+Use a custom fetch implementation (e.g., for testing):
+
+```typescript
+const client = new FetchClient({
+  fetch: async (request) => {
+    // Custom logic (e.g., mock responses, logging)
+    console.log('Custom fetch:', request.url);
+    return globalThis.fetch(request);
+  },
+});
+```
+
+## Best Practices
+
+1. **Reuse client instances** — Create one client per base URL, not per request
+2. **Use typed responses** — Always specify the response type for better IDE support
+3. **Handle errors explicitly** — Catch specific error classes for better error handling
+4. **Configure retries wisely** — Use exponential backoff for transient failures
+5. **Add request logging in development** — Use `beforeRequest` hook for debugging
+6. **Validate responses in development** — Use `@vertz/schema` + `afterResponse` hook
+7. **Use streaming for large responses** — `requestStream` is more memory-efficient
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+type AuthStrategy = {
+	type: "bearer";
+	token: string | (() => string | Promise<string>);
+} | {
+	type: "basic";
+	username: string;
+	password: string;
+} | {
+	type: "apiKey";
+	key: string | (() => string | Promise<string>);
+	location: "header" | "query" | "cookie";
+	name: string;
+} | {
+	type: "custom";
+	apply: (request: Request) => Request | Promise<Request>;
+};
+interface RetryConfig {
+	retries: number;
+	strategy: "exponential" | "linear" | ((attempt: number, baseBackoff: number) => number);
+	backoffMs: number;
+	retryOn: number[];
+	retryOnError?: (error: Error) => boolean;
+}
+type StreamingFormat = "sse" | "ndjson";
+interface HooksConfig {
+	beforeRequest?: (request: Request) => void | Promise<void>;
+	afterResponse?: (response: Response) => void | Promise<void>;
+	onError?: (error: Error) => void | Promise<void>;
+	beforeRetry?: (attempt: number, error: Error) => void | Promise<void>;
+	onStreamStart?: () => void;
+	onStreamChunk?: (chunk: unknown) => void;
+	onStreamEnd?: () => void;
+}
+interface FetchClientConfig {
+	baseURL?: string;
+	headers?: Record<string, string>;
+	timeoutMs?: number;
+	retry?: Partial<RetryConfig>;
+	hooks?: HooksConfig;
+	authStrategies?: AuthStrategy[];
+	fetch?: typeof fetch;
+	credentials?: RequestCredentials;
+}
+interface RequestOptions {
+	headers?: Record<string, string>;
+	query?: Record<string, unknown>;
+	body?: unknown;
+	signal?: AbortSignal;
+}
+interface FetchResponse<T> {
+	data: T;
+	status: number;
+	headers: Headers;
+}
+interface StreamingRequestOptions extends RequestOptions {
+	format: StreamingFormat;
+}
+declare class FetchClient {
+	private readonly config;
+	private readonly fetchFn;
+	constructor(config: FetchClientConfig);
+	request<T>(method: string, path: string, options?: RequestOptions): Promise<FetchResponse<T>>;
+	requestStream<T>(options: StreamingRequestOptions & {
+		method: string;
+		path: string;
+	}): AsyncGenerator<T>;
+	private parseSSEBuffer;
+	private parseNDJSONBuffer;
+	private buildSignal;
+	private resolveRetryConfig;
+	private calculateBackoff;
+	private sleep;
+	private buildURL;
+	private applyAuth;
+	private applyStrategy;
+	private safeParseJSON;
+}
+declare class FetchError extends Error {
+	readonly status: number;
+	readonly body?: unknown;
+	constructor(message: string, status: number, body?: unknown);
+}
+declare class BadRequestError extends FetchError {
+	constructor(message: string, body?: unknown);
+}
+declare class UnauthorizedError extends FetchError {
+	constructor(message: string, body?: unknown);
+}
+declare class ForbiddenError extends FetchError {
+	constructor(message: string, body?: unknown);
+}
+declare class NotFoundError extends FetchError {
+	constructor(message: string, body?: unknown);
+}
+declare class ConflictError extends FetchError {
+	constructor(message: string, body?: unknown);
+}
+declare class GoneError extends FetchError {
+	constructor(message: string, body?: unknown);
+}
+declare class UnprocessableEntityError extends FetchError {
+	constructor(message: string, body?: unknown);
+}
+declare class RateLimitError extends FetchError {
+	constructor(message: string, body?: unknown);
+}
+declare class InternalServerError extends FetchError {
+	constructor(message: string, body?: unknown);
+}
+declare class ServiceUnavailableError extends FetchError {
+	constructor(message: string, body?: unknown);
+}
+declare function createErrorFromStatus(status: number, message: string, body?: unknown): FetchError;
+export { createErrorFromStatus, UnprocessableEntityError, UnauthorizedError, StreamingRequestOptions, StreamingFormat, ServiceUnavailableError, RetryConfig, RequestOptions, RateLimitError, NotFoundError, InternalServerError, HooksConfig, GoneError, ForbiddenError, FetchResponse, FetchError, FetchClientConfig, FetchClient, ConflictError, BadRequestError, AuthStrategy };

package/dist/index.js

@@ -0,0 +1,363 @@
+// src/errors.ts
+class FetchError extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "FetchError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+class BadRequestError extends FetchError {
+  constructor(message, body) {
+    super(message, 400, body);
+    this.name = "BadRequestError";
+  }
+}
+
+class UnauthorizedError extends FetchError {
+  constructor(message, body) {
+    super(message, 401, body);
+    this.name = "UnauthorizedError";
+  }
+}
+
+class ForbiddenError extends FetchError {
+  constructor(message, body) {
+    super(message, 403, body);
+    this.name = "ForbiddenError";
+  }
+}
+
+class NotFoundError extends FetchError {
+  constructor(message, body) {
+    super(message, 404, body);
+    this.name = "NotFoundError";
+  }
+}
+
+class ConflictError extends FetchError {
+  constructor(message, body) {
+    super(message, 409, body);
+    this.name = "ConflictError";
+  }
+}
+
+class GoneError extends FetchError {
+  constructor(message, body) {
+    super(message, 410, body);
+    this.name = "GoneError";
+  }
+}
+
+class UnprocessableEntityError extends FetchError {
+  constructor(message, body) {
+    super(message, 422, body);
+    this.name = "UnprocessableEntityError";
+  }
+}
+
+class RateLimitError extends FetchError {
+  constructor(message, body) {
+    super(message, 429, body);
+    this.name = "RateLimitError";
+  }
+}
+
+class InternalServerError extends FetchError {
+  constructor(message, body) {
+    super(message, 500, body);
+    this.name = "InternalServerError";
+  }
+}
+
+class ServiceUnavailableError extends FetchError {
+  constructor(message, body) {
+    super(message, 503, body);
+    this.name = "ServiceUnavailableError";
+  }
+}
+var errorMap = {
+  400: BadRequestError,
+  401: UnauthorizedError,
+  403: ForbiddenError,
+  404: NotFoundError,
+  409: ConflictError,
+  410: GoneError,
+  422: UnprocessableEntityError,
+  429: RateLimitError,
+  500: InternalServerError,
+  503: ServiceUnavailableError
+};
+function createErrorFromStatus(status, message, body) {
+  const ErrorClass = errorMap[status];
+  if (ErrorClass) {
+    return new ErrorClass(message, body);
+  }
+  return new FetchError(message, status, body);
+}
+
+// src/client.ts
+var DEFAULT_RETRY_ON = [429, 500, 502, 503, 504];
+
+class FetchClient {
+  config;
+  fetchFn;
+  constructor(config) {
+    this.config = config;
+    this.fetchFn = config.fetch ?? globalThis.fetch;
+  }
+  async request(method, path, options) {
+    const retryConfig = this.resolveRetryConfig();
+    let lastError;
+    for (let attempt = 0;attempt <= retryConfig.retries; attempt++) {
+      if (attempt > 0) {
+        const delay = this.calculateBackoff(attempt, retryConfig);
+        await this.sleep(delay);
+      }
+      const url = this.buildURL(path, options?.query);
+      const headers = new Headers(this.config.headers);
+      if (options?.headers) {
+        for (const [key, value] of Object.entries(options.headers)) {
+          headers.set(key, value);
+        }
+      }
+      const signal = this.buildSignal(options?.signal);
+      const request = new Request(url, {
+        method,
+        headers,
+        body: options?.body !== undefined ? JSON.stringify(options.body) : undefined,
+        signal
+      });
+      if (options?.body !== undefined) {
+        request.headers.set("Content-Type", "application/json");
+      }
+      const authedRequest = await this.applyAuth(request);
+      await this.config.hooks?.beforeRequest?.(authedRequest);
+      const response = await this.fetchFn(authedRequest);
+      if (!response.ok) {
+        const body = await this.safeParseJSON(response);
+        const error = createErrorFromStatus(response.status, response.statusText, body);
+        if (attempt < retryConfig.retries && retryConfig.retryOn.includes(response.status)) {
+          lastError = error;
+          await this.config.hooks?.beforeRetry?.(attempt + 1, error);
+          continue;
+        }
+        await this.config.hooks?.onError?.(error);
+        throw error;
+      }
+      await this.config.hooks?.afterResponse?.(response);
+      const data = await response.json();
+      return {
+        data,
+        status: response.status,
+        headers: response.headers
+      };
+    }
+    throw lastError;
+  }
+  async* requestStream(options) {
+    const url = this.buildURL(options.path, options.query);
+    const headers = new Headers(this.config.headers);
+    if (options.headers) {
+      for (const [key, value] of Object.entries(options.headers)) {
+        headers.set(key, value);
+      }
+    }
+    if (options.format === "sse") {
+      headers.set("Accept", "text/event-stream");
+    } else {
+      headers.set("Accept", "application/x-ndjson");
+    }
+    const signal = this.buildSignal(options.signal);
+    const request = new Request(url, {
+      method: options.method,
+      headers,
+      body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+      signal
+    });
+    const authedRequest = await this.applyAuth(request);
+    await this.config.hooks?.beforeRequest?.(authedRequest);
+    const response = await this.fetchFn(authedRequest);
+    if (!response.ok) {
+      const body = await this.safeParseJSON(response);
+      const error = createErrorFromStatus(response.status, response.statusText, body);
+      await this.config.hooks?.onError?.(error);
+      throw error;
+    }
+    if (!response.body) {
+      return;
+    }
+    this.config.hooks?.onStreamStart?.();
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder;
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+          break;
+        buffer += decoder.decode(value, { stream: true });
+        if (options.format === "sse") {
+          yield* this.parseSSEBuffer(buffer, (remaining) => {
+            buffer = remaining;
+          });
+        } else {
+          yield* this.parseNDJSONBuffer(buffer, (remaining) => {
+            buffer = remaining;
+          });
+        }
+      }
+    } finally {
+      reader.releaseLock();
+      this.config.hooks?.onStreamEnd?.();
+    }
+  }
+  *parseSSEBuffer(buffer, setRemaining) {
+    const events = buffer.split(`
+
+`);
+    const remaining = events.pop() ?? "";
+    setRemaining(remaining);
+    for (const event of events) {
+      if (!event.trim())
+        continue;
+      const lines = event.split(`
+`);
+      let data = "";
+      for (const line of lines) {
+        if (line.startsWith("data: ")) {
+          data += line.slice(6);
+        } else if (line.startsWith("data:")) {
+          data += line.slice(5);
+        }
+      }
+      if (data) {
+        const parsed = JSON.parse(data);
+        this.config.hooks?.onStreamChunk?.(parsed);
+        yield parsed;
+      }
+    }
+  }
+  *parseNDJSONBuffer(buffer, setRemaining) {
+    const lines = buffer.split(`
+`);
+    const remaining = lines.pop() ?? "";
+    setRemaining(remaining);
+    for (const line of lines) {
+      if (!line.trim())
+        continue;
+      const parsed = JSON.parse(line);
+      this.config.hooks?.onStreamChunk?.(parsed);
+      yield parsed;
+    }
+  }
+  buildSignal(userSignal) {
+    const timeoutMs = this.config.timeoutMs;
+    if (!timeoutMs && !userSignal)
+      return;
+    if (!timeoutMs)
+      return userSignal;
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    if (!userSignal)
+      return timeoutSignal;
+    return AbortSignal.any([userSignal, timeoutSignal]);
+  }
+  resolveRetryConfig() {
+    const userConfig = this.config.retry;
+    return {
+      retries: userConfig?.retries ?? 0,
+      strategy: userConfig?.strategy ?? "exponential",
+      backoffMs: userConfig?.backoffMs ?? 100,
+      retryOn: userConfig?.retryOn ?? DEFAULT_RETRY_ON,
+      retryOnError: userConfig?.retryOnError
+    };
+  }
+  calculateBackoff(attempt, config) {
+    const { strategy, backoffMs } = config;
+    if (typeof strategy === "function") {
+      return strategy(attempt, backoffMs);
+    }
+    if (strategy === "linear") {
+      return backoffMs * attempt;
+    }
+    return backoffMs * 2 ** (attempt - 1);
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  buildURL(path, query) {
+    const base = this.config.baseURL;
+    const url = base ? new URL(path, base) : new URL(path);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+  async applyAuth(request) {
+    const strategies = this.config.authStrategies;
+    if (!strategies)
+      return request;
+    let current = request;
+    for (const strategy of strategies) {
+      current = await this.applyStrategy(current, strategy);
+    }
+    return current;
+  }
+  async applyStrategy(request, strategy) {
+    switch (strategy.type) {
+      case "bearer": {
+        const token = typeof strategy.token === "function" ? await strategy.token() : strategy.token;
+        request.headers.set("Authorization", `Bearer ${token}`);
+        return request;
+      }
+      case "basic": {
+        const encoded = btoa(`${strategy.username}:${strategy.password}`);
+        request.headers.set("Authorization", `Basic ${encoded}`);
+        return request;
+      }
+      case "apiKey": {
+        const key = typeof strategy.key === "function" ? await strategy.key() : strategy.key;
+        if (strategy.location === "header") {
+          request.headers.set(strategy.name, key);
+        } else if (strategy.location === "query") {
+          const url = new URL(request.url);
+          url.searchParams.set(strategy.name, key);
+          return new Request(url, request);
+        }
+        return request;
+      }
+      case "custom": {
+        return await strategy.apply(request);
+      }
+    }
+  }
+  async safeParseJSON(response) {
+    try {
+      return await response.json();
+    } catch {
+      return;
+    }
+  }
+}
+export {
+  createErrorFromStatus,
+  UnprocessableEntityError,
+  UnauthorizedError,
+  ServiceUnavailableError,
+  RateLimitError,
+  NotFoundError,
+  InternalServerError,
+  GoneError,
+  ForbiddenError,
+  FetchError,
+  FetchClient,
+  ConflictError,
+  BadRequestError
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@vertz/fetch",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Type-safe HTTP client for Vertz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vertz-dev/vertz.git",
+    "directory": "packages/fetch"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bunup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "bunup": "latest",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false
+}