The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.
TypeScript clickhousemysqlnextjsopen-sourceplanetscaleprismatailwindcsstinybirdtypescriptupstashvercel
import { logger } from "@/lib/axiom/server";
import { waitUntil } from "@vercel/functions";
import * as z from "zod/v4";
const DEFAULT_TIMEOUT_MS = 30_000;
const MAX_LOGGED_BODY_LENGTH = 2_000;
type QueryValue = string | number | boolean | null | undefined;
export interface HttpRequestOptions<
TInput extends z.ZodType = z.ZodType,
TOutput extends z.ZodType = z.ZodType,
> {
// request input — validated with inputSchema when provided, then sent as
// query params for GET/DELETE requests or as the request body otherwise
input?: z.input<TInput>;
inputSchema?: TInput;
outputSchema: TOutput;
headers?: Record<string, string>;
bodyType?: "json" | "form";
timeout?: number;
signal?: AbortSignal;
}
export class HttpClientError extends Error {
readonly vendor: string;
readonly method: string;
readonly url: string;
readonly status: number | null;
readonly responseBody: string | null;
constructor({
vendor,
method,
url,
status,
responseBody,
message,
}: {
vendor: string;
method: string;
url: string;
status: number | null;
responseBody: string | null;
message: string;
}) {
super(message);
this.name = "HttpClientError";
this.vendor = vendor;
this.method = method;
this.url = url;
this.status = status;
this.responseBody = responseBody;
}
}
// Base class for external vendor API clients.
export abstract class HttpBaseClient {
protected abstract readonly vendor: string;
protected abstract readonly baseUrl: string;
// Header-based auth. Return {} for vendors that authenticate via query
// params. Called per-request, so env validation belongs here
protected abstract buildAuthHeaders():
| Record<string, string>
| Promise<Record<string, string>>;
// Override for vendors that authenticate via query params. Any secret param
// must also be listed in redactedQueryParams.
protected buildAuthQuery(): Record<string, string> {
return {};
}
// Query params whose values are replaced with "REDACTED" in every log
// message and error. Request headers are never logged.
protected readonly redactedQueryParams: string[] = [];
// When false, response bodies are omitted from Axiom/console logs and
// HttpClientError (for vendors that return PII).
protected readonly logResponseBodies: boolean = true;
// Override to translate HTTP failures into vendor-specific errors
// (e.g. a DubApiError with a caller-facing message).
protected mapError({
method,
url,
status,
responseBody,
}: {
method: string;
url: string;
status: number;
responseBody: string | null;
data: unknown;
}): Error {
return new HttpClientError({
vendor: this.vendor,
method,
url,
status,
responseBody,
message: `[${this.vendor}] ${method} ${url} failed with status ${status}`,
});
}
private readonly debug: boolean;
private readonly timeout: number;
constructor({
debug,
timeout,
}: {
debug?: boolean;
timeout?: number;
} = {}) {
this.debug = debug ?? process.env.NODE_ENV === "development";
this.timeout = timeout ?? DEFAULT_TIMEOUT_MS;
}
async get<TInput extends z.ZodType, TOutput extends z.ZodType>(
path: string,
options: HttpRequestOptions<TInput, TOutput>,
): Promise<z.output<TOutput>> {
return this.request("GET", path, options);
}
async post<TInput extends z.ZodType, TOutput extends z.ZodType>(
path: string,
options: HttpRequestOptions<TInput, TOutput>,
): Promise<z.output<TOutput>> {
return this.request("POST", path, options);
}
async put<TInput extends z.ZodType, TOutput extends z.ZodType>(
path: string,
options: HttpRequestOptions<TInput, TOutput>,
): Promise<z.output<TOutput>> {
return this.request("PUT", path, options);
}
async patch<TInput extends z.ZodType, TOutput extends z.ZodType>(
path: string,
options: HttpRequestOptions<TInput, TOutput>,
): Promise<z.output<TOutput>> {
return this.request("PATCH", path, options);
}
async delete<TInput extends z.ZodType, TOutput extends z.ZodType>(
path: string,
options: HttpRequestOptions<TInput, TOutput>,
): Promise<z.output<TOutput>> {
return this.request("DELETE", path, options);
}
private async request<TInput extends z.ZodType, TOutput extends z.ZodType>(
method: string,
path: string,
options: HttpRequestOptions<TInput, TOutput>,
): Promise<z.output<TOutput>> {
const url = new URL(`${this.baseUrl}${path}`);
let input: unknown = options.input;
if (options.inputSchema && options.input !== undefined) {
const parsedInput = options.inputSchema.safeParse(options.input);
if (!parsedInput.success) {
const safeUrl = this.redactUrl(url);
const message = `[${this.vendor}] ${method} ${safeUrl} request validation failed`;
waitUntil(
this.logError(message, {
method,
url: safeUrl,
status: null,
issues: z.prettifyError(parsedInput.error),
}),
);
throw new HttpClientError({
vendor: this.vendor,
method,
url: safeUrl,
status: null,
responseBody: null,
message,
});
}
input = parsedInput.data;
}
// GET/DELETE requests carry no body — their input becomes query params
const inputAsQuery = method === "GET" || method === "DELETE";
let query: Record<string, QueryValue | QueryValue[]> | undefined;
if (inputAsQuery && input !== undefined) {
query = input as Record<string, QueryValue | QueryValue[]>;
}
this.buildQueryParams(url, query);
const safeUrl = this.redactUrl(url);
let body: BodyInit | undefined;
const headers: Record<string, string> = {};
if (!inputAsQuery && input !== undefined) {
if (options.bodyType === "form") {
body = new URLSearchParams(input as Record<string, string>);
} else {
body = JSON.stringify(input);
headers["Content-Type"] = "application/json";
}
}
Object.assign(headers, await this.buildAuthHeaders(), options.headers);
const signal =
options.signal ?? AbortSignal.timeout(options.timeout ?? this.timeout);
let response: Response;
try {
response = await fetch(url, {
method,
headers,
body,
signal,
});
} catch (error) {
const reason = error instanceof Error ? error.message : String(error);
const message = `[${this.vendor}] ${method} ${safeUrl} network error: ${reason}`;
waitUntil(
this.logError(message, {
method,
url: safeUrl,
status: null,
error: reason,
}),
);
throw new HttpClientError({
vendor: this.vendor,
method,
url: safeUrl,
status: null,
responseBody: null,
message,
});
}
// The body read can still fail after the headers arrived (a timeout or a dropped connection).
// On a successful status, report it like a network error, so callers can retry it the same way.
// On an error status, keep the status: the vendor rejected the request, only the error body is missing.
let text: string;
try {
text = await response.text();
} catch (error) {
if (!response.ok) {
text = "";
} else {
throw this.bodyReadError({ method, safeUrl, response, error });
}
}
let data: unknown = null;
if (text) {
try {
data = JSON.parse(text);
} catch {
data = text;
}
}
if (this.debug) {
console.log(
`[${this.vendor}] ${method} ${safeUrl} -> ${response.status}`,
...(this.logResponseBodies ? [data] : []),
);
}
if (!response.ok) {
const responseBody = this.responseBodyForLog(text);
waitUntil(
this.logError(
`[${this.vendor}] ${method} ${safeUrl} failed with status ${response.status}`,
{
method,
url: safeUrl,
status: response.status,
responseBody,
},
),
);
throw this.mapError({
method,
url: safeUrl,
status: response.status,
responseBody,
data,
});
}
const parsed = options.outputSchema.safeParse(data);
if (!parsed.success) {
const message = `[${this.vendor}] ${method} ${safeUrl} response validation failed`;
const responseBody = this.responseBodyForLog(text);
waitUntil(
this.logError(message, {
method,
url: safeUrl,
status: response.status,
issues: z.prettifyError(parsed.error),
responseBody,
}),
);
throw new HttpClientError({
vendor: this.vendor,
method,
url: safeUrl,
status: response.status,
responseBody,
message,
});
}
return parsed.data as z.output<TOutput>;
}
// A failed body read on a successful status, reported like a network error (null status)
private bodyReadError({
method,
safeUrl,
response,
error,
}: {
method: string;
safeUrl: string;
response: Response;
error: unknown;
}) {
const reason = error instanceof Error ? error.message : String(error);
const message = `[${this.vendor}] ${method} ${safeUrl} network error while reading the response: ${reason}`;
waitUntil(
this.logError(message, {
method,
url: safeUrl,
status: response.status,
error: reason,
}),
);
return new HttpClientError({
vendor: this.vendor,
method,
url: safeUrl,
status: null,
responseBody: null,
message,
});
}
private buildQueryParams(
url: URL,
query: Record<string, QueryValue | QueryValue[]> = {},
) {
const merged = {
...query,
...this.buildAuthQuery(),
};
for (const [key, value] of Object.entries(merged)) {
if (value === null || value === undefined) {
continue;
}
if (Array.isArray(value)) {
for (const item of value) {
if (item === null || item === undefined) {
continue;
}
url.searchParams.append(key, String(item));
}
} else {
url.searchParams.append(key, String(value));
}
}
}
private redactUrl(url: URL): string {
const safe = new URL(url);
for (const param of this.redactedQueryParams) {
if (safe.searchParams.has(param)) {
safe.searchParams.set(param, "REDACTED");
}
}
return safe.toString();
}
private responseBodyForLog(text: string): string | null {
if (!this.logResponseBodies) {
return null;
}
return this.truncate(text);
}
private truncate(text: string): string | null {
if (!text) {
return null;
}
return text.slice(0, MAX_LOGGED_BODY_LENGTH);
}
private async logError(message: string, metadata: Record<string, unknown>) {
console.error(message, metadata);
logger.error(message, {
vendor: this.vendor,
...metadata,
});
await logger.flush();
}
}