managarten/packages/shared-config/src/api.ts

/**
 * API endpoint construction utilities
 */

/**
 * API configuration
 */
export interface ApiConfig {
	/** Base URL for the API */
	baseUrl: string;
	/** API version prefix (e.g., 'v1') */
	version?: string;
	/** Default timeout in milliseconds */
	timeout?: number;
	/** Default headers */
	headers?: Record<string, string>;
}

/**
 * Create API endpoint URL builder
 */
export function createApiBuilder(config: ApiConfig) {
	const { baseUrl, version } = config;

	// Remove trailing slash from base URL
	const base = baseUrl.replace(/\/$/, '');

	// Build base path with optional version
	const basePath = version ? `${base}/${version}` : base;

	return {
		/**
		 * Build endpoint URL from path segments
		 */
		endpoint(...segments: (string | number)[]): string {
			const path = segments
				.map(String)
				.map((s) => s.replace(/^\/+|\/+$/g, '')) // Remove leading/trailing slashes
				.filter(Boolean)
				.join('/');

			return `${basePath}/${path}`;
		},

		/**
		 * Build endpoint URL with query parameters
		 */
		endpointWithQuery(
			path: string | string[],
			params?: Record<string, string | number | boolean | undefined>
		): string {
			const segments = Array.isArray(path) ? path : [path];
			const url = this.endpoint(...segments);

			if (!params) {
				return url;
			}

			const searchParams = new URLSearchParams();
			for (const [key, value] of Object.entries(params)) {
				if (value !== undefined) {
					searchParams.append(key, String(value));
				}
			}

			const queryString = searchParams.toString();
			return queryString ? `${url}?${queryString}` : url;
		},

		/**
		 * Get the base URL
		 */
		getBaseUrl(): string {
			return basePath;
		},

		/**
		 * Get the config
		 */
		getConfig(): ApiConfig {
			return config;
		},
	};
}

/**
 * Build URL with query parameters
 */
export function buildUrl(
	baseUrl: string,
	path: string,
	params?: Record<string, string | number | boolean | undefined>
): string {
	// Ensure single slash between base and path
	const base = baseUrl.replace(/\/$/, '');
	const cleanPath = path.replace(/^\//, '');
	const url = `${base}/${cleanPath}`;

	if (!params) {
		return url;
	}

	const searchParams = new URLSearchParams();
	for (const [key, value] of Object.entries(params)) {
		if (value !== undefined) {
			searchParams.append(key, String(value));
		}
	}

	const queryString = searchParams.toString();
	return queryString ? `${url}?${queryString}` : url;
}

/**
 * Parse URL and extract components
 */
export function parseUrl(url: string): {
	protocol: string;
	host: string;
	port: string;
	pathname: string;
	search: string;
	params: Record<string, string>;
} {
	const urlObj = new URL(url);

	const params: Record<string, string> = {};
	urlObj.searchParams.forEach((value, key) => {
		params[key] = value;
	});

	return {
		protocol: urlObj.protocol.replace(':', ''),
		host: urlObj.hostname,
		port: urlObj.port,
		pathname: urlObj.pathname,
		search: urlObj.search,
		params,
	};
}

/**
 * Join URL path segments
 */
export function joinPath(...segments: string[]): string {
	return segments
		.map((s) => s.replace(/^\/+|\/+$/g, ''))
		.filter(Boolean)
		.join('/');
}

/**
 * Common HTTP methods
 */
export const HTTP_METHODS = {
	GET: 'GET',
	POST: 'POST',
	PUT: 'PUT',
	PATCH: 'PATCH',
	DELETE: 'DELETE',
	HEAD: 'HEAD',
	OPTIONS: 'OPTIONS',
} as const;

export type HttpMethod = (typeof HTTP_METHODS)[keyof typeof HTTP_METHODS];

/**
 * Common HTTP status codes
 */
export const HTTP_STATUS = {
	OK: 200,
	CREATED: 201,
	NO_CONTENT: 204,
	BAD_REQUEST: 400,
	UNAUTHORIZED: 401,
	FORBIDDEN: 403,
	NOT_FOUND: 404,
	CONFLICT: 409,
	UNPROCESSABLE_ENTITY: 422,
	TOO_MANY_REQUESTS: 429,
	INTERNAL_SERVER_ERROR: 500,
	BAD_GATEWAY: 502,
	SERVICE_UNAVAILABLE: 503,
} as const;

export type HttpStatus = (typeof HTTP_STATUS)[keyof typeof HTTP_STATUS];

/**
 * Check if status code is successful (2xx)
 */
export function isSuccessStatus(status: number): boolean {
	return status >= 200 && status < 300;
}

/**
 * Check if status code is client error (4xx)
 */
export function isClientError(status: number): boolean {
	return status >= 400 && status < 500;
}

/**
 * Check if status code is server error (5xx)
 */
export function isServerError(status: number): boolean {
	return status >= 500 && status < 600;
}