@tpzdsp/next-toolkit 1.6.0 → 1.8.0

package/src/errors/ApiError.ts

@@ -1,33 +1,95 @@
 /* eslint-disable no-restricted-syntax */
 
-import { Http } from '../utils/http';
+import z from 'zod/v4';
 
-export class ApiError extends Error {
+import { HttpStatus, HttpStatusText } from '../http';
+
+/**
+ * Schema defining the JSON shape of error responses returned by a server. (The proxy is where
+ * the error is used the most, though it isn't unique to the proxy and may be used elsewhere).
+ *
+ * Note: This schema intentionally excludes the HTTP `status` field,
+ * as that value is carried in the HTTP response itself (via the status code)
+ * and in the in-memory {@link ApiError} class for internal use.
+ */
+export const ApiErrorSchema = z.object({
+  message: z.string(),
+  details: z.string().nullable(),
+});
+
+export type ApiErrorSchemaOutput = z.output<typeof ApiErrorSchema>;
+
+/**
+ * Represents an error that can be returned by an API or proxy endpoint.
+ *
+ * Use this class to consistently capture errors along with an HTTP status
+ * code and optional detailed message. This allows:
+ * - Returning structured errors from API handlers or internal proxies.
+ * - Setting the status code for the response when an error has occurred.
+ * - Including additional context in `details` for debugging.
+ *
+ * Note:
+ * - Although it contains the same members, this class is separate from {@link ApiErrorSchema}.
+ *   The schema defines the serialized JSON payload returned to clients, while this class
+ *   *also* includes meta information of the response, such as the HTTP status code.
+ *   The status code is typically only used internally inside the proxy (to forward status codes),
+ *   but it could be accessed if a request 1 made with `throw` set to `false.`
+ */
+export class ApiError extends Error implements z.output<typeof ApiErrorSchema> {
+  public readonly details: string | null;
+  public readonly digest: string;
   public readonly status: number;
-  public readonly code?: string;
-  public readonly details?: unknown;
+  // `true` if this class was reconstructed on the client from an response from the proxy
+  private readonly rehydrated: boolean;
 
-  constructor(message: string, status: number, code?: string, details?: unknown) {
+  constructor(
+    message: string,
+    status: number,
+    details?: string | null,
+    options?: { rehydrated?: boolean },
+  ) {
     super(message);
+
     this.name = 'ApiError';
     this.status = status;
-    this.code = code;
-    this.details = details;
+    this.details = details ?? null;
+    this.digest = crypto.randomUUID();
+    this.rehydrated = options?.rehydrated ?? false;
 
     // Maintains proper stack trace for where our error was thrown (only available on V8)
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, ApiError);
     }
+
+    this.logError();
+  }
+
+  private logError() {
+    const trimmedStack = this.stack
+      ?.split('\n')
+      // Filter out noisy frames but keep traces from toolkit for debugging
+      .filter((line) => !line.includes('node_modules') || line.includes('next-toolkit'))
+      .join('\n');
+
+    const prefix =
+      !this.rehydrated && typeof window !== 'undefined' ? 'Client API Error' : 'Server API Error';
+
+    console.error(
+      // eslint-disable-next-line sonarjs/no-nested-template-literals
+      `[${prefix}]: ${this.message}${this.details ? ` (${this.details})` : ''}. Digest: ${
+        this.digest
+      }\n${!this.rehydrated ? (trimmedStack ?? 'aa') : 'bb'}`,
+    );
   }
 
   // Helper method to check if it's a client error (4xx)
   get isClientError(): boolean {
-    return this.status >= Http.BadRequest && this.status < Http.InternalServerError;
+    return this.status >= HttpStatus.BadRequest && this.status < HttpStatus.InternalServerError;
   }
 
   // Helper method to check if it's a server error (5xx)
   get isServerError(): boolean {
-    return this.status >= Http.InternalServerError;
+    return this.status >= HttpStatus.InternalServerError;
   }
 
   // Convert to a plain object for JSON serialization
@@ -36,36 +98,48 @@ export class ApiError extends Error {
       name: this.name,
       message: this.message,
       status: this.status,
-      code: this.code,
       details: this.details,
     };
   }
 
   // Static factory methods for common error types
-  static badRequest(message: string, details?: unknown): ApiError {
-    return new ApiError(message, Http.BadRequest, 'BAD_REQUEST', details);
+  static badRequest(details?: string): ApiError {
+    return new ApiError(HttpStatusText.BadRequest, HttpStatus.BadRequest, details);
+  }
+
+  static notFound(details?: string): ApiError {
+    return new ApiError(HttpStatusText.NotFound, HttpStatus.NotFound, details);
   }
 
-  static notFound(message = 'Resource not found'): ApiError {
-    return new ApiError(message, Http.NotFound, 'NOT_FOUND');
+  static unauthorized(details?: string): ApiError {
+    return new ApiError(HttpStatusText.Unauthorized, HttpStatus.Unauthorized, details);
   }
 
-  static unauthorized(message = 'Unauthorized'): ApiError {
-    return new ApiError(message, Http.Unauthorized, 'UNAUTHORIZED');
+  static notAllowed(details?: string): ApiError {
+    return new ApiError(HttpStatusText.NotAllowed, HttpStatus.NotAllowed, details);
   }
 
-  static forbidden(message = 'Forbidden'): ApiError {
-    return new ApiError(message, Http.Forbidden, 'FORBIDDEN');
+  static notImplemented(details?: string): ApiError {
+    return new ApiError(HttpStatusText.NotImplemented, HttpStatus.NotImplemented, details);
   }
 
-  static internalServerError(message = 'Internal server error'): ApiError {
-    return new ApiError(message, Http.InternalServerError, 'INTERNAL_SERVER_ERROR');
+  static forbidden(details?: string): ApiError {
+    return new ApiError(HttpStatusText.Forbidden, HttpStatus.Forbidden, details);
+  }
+
+  static unprocessableContent(details?: string): ApiError {
+    return new ApiError(
+      HttpStatusText.UnprocessableContent,
+      HttpStatus.UnprocessableContent,
+      details,
+    );
   }
 
-  static fromResponse(response: Response, message?: string): ApiError {
+  static internalServerError(details?: string): ApiError {
     return new ApiError(
-      message ?? `HTTP ${response.status}: ${response.statusText}`,
-      response.status,
+      HttpStatusText.InternalServerError,
+      HttpStatus.InternalServerError,
+      details,
     );
   }
 }

package/src/http/constants.ts

@@ -0,0 +1,111 @@
+/**
+ * Use the {@link MimeTypes} type for a union type containing these mime types.
+ */
+export const MimeType = {
+  Json: 'application/json',
+  JsonLd: 'application/ld+json',
+  GeoJson: 'application/geo+json',
+  Png: 'image/png',
+  XJsonLines: 'application/x-jsonlines',
+  Csv: 'text/csv',
+  Form: 'application/x-www-form-urlencoded',
+  Text: 'text/plain',
+} as const;
+
+/**
+ * Use the {@link MimeType} object for named constants of each mime type.
+ */
+export type MimeTypes = (typeof MimeType)[keyof typeof MimeType];
+
+/**
+ * Returns `true` if the mime type is a non-streamed JSON mime type (I.E. not JSON X-Lines).
+ */
+export const isJsonMimeType = (mime: MimeTypes | string | null): boolean => {
+  return ([MimeType.Json, MimeType.GeoJson, MimeType.JsonLd] as string[]).includes(mime ?? '');
+};
+
+/**
+ * Returns `true` if the mime type is a plain-text mime type.
+ */
+export const isTextMimeType = (mime: MimeTypes | string | null): boolean => {
+  return ([MimeType.Text, MimeType.Csv] as string[]).includes(mime ?? '');
+};
+
+/**
+ * Use the {@link HttpStatuses} type for a union type containing these status codes.
+ *
+ * Use the {@link HttpStatusText} object for the status text represented by each code.
+ */
+export const HttpStatus = {
+  Ok: 200,
+  Created: 201,
+  NoContent: 204,
+  BadRequest: 400,
+  Unauthorized: 401,
+  Forbidden: 403,
+  NotFound: 404,
+  NotAllowed: 405,
+  UnprocessableContent: 422,
+  InternalServerError: 500,
+  NotImplemented: 501,
+} as const;
+
+/**
+ * Use the {@link HttpStatus} object for named constants of each status code.
+ */
+export type HttpStatuses = (typeof HttpStatus)[keyof typeof HttpStatus];
+
+/**
+ * Status texts for each status code.
+ */
+export const HttpStatusText = {
+  Ok: 'OK',
+  Created: 'Created',
+  NoContent: 'No Content',
+  BadRequest: 'Bad Request',
+  Unauthorized: 'Unauthorized',
+  Forbidden: 'Forbidden',
+  NotFound: 'Not Found',
+  NotAllowed: 'Method Not Allowed',
+  UnprocessableContent: 'Unprocessable Content',
+  InternalServerError: 'Internal Server Error',
+  NotImplemented: 'Not Implemented',
+} as const;
+
+/**
+ * Use the {@link HttpMethods} type for a union type containing these method verbs.
+ */
+export const HttpMethod = {
+  Get: 'get',
+  Post: 'post',
+  Put: 'put',
+  Patch: 'patch',
+  Delete: 'delete',
+} as const;
+
+/**
+ * Use the {@link HttpMethod} object for named constants of each method verb.
+ */
+export type HttpMethods = (typeof HttpMethod)[keyof typeof HttpMethod];
+
+/**
+ * Use the {@link Headers} type for a union type containing these headers.
+ */
+export const Header = {
+  ContentType: 'Content-Type',
+  ContentDisposition: 'Content-Disposition',
+  Accept: 'Accept',
+  AcceptCrs: 'Accept-Crs',
+  CsvHeader: 'CSV-Header',
+  XTotalItems: 'X-Total-Items',
+  XRequestId: 'X-Request-ID',
+} as const;
+
+/**
+ * Use the {@link Header} object for named constants of each header.
+ */
+export type Headers = (typeof Header)[keyof typeof Header];
+
+// Special types used for downloading files via a `POST` request
+export const SPECIAL_FORM_DATA_TYPE = '_type';
+export const SPECIAL_FORM_DOWNLOAD_POST = 'file-download';

package/src/http/fetch.ts

@@ -0,0 +1,263 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import z from 'zod/v4';
+
+import {
+  createSchema as betterFetchCreateSchema,
+  createFetch as betterFetchCreateFetch,
+  type CreateFetchOption as BetterFetchCreateFetchOption,
+  type Schema,
+  type FetchSchema,
+  ValidationError,
+  BetterFetchError,
+  type BetterFetch,
+  type StandardSchemaV1,
+  type BetterFetchPlugin,
+} from '@better-fetch/fetch';
+
+import { ApiError } from '../errors';
+import { Header, isJsonMimeType, MimeType, type HttpMethods } from './constants';
+import { HttpStatus } from './constants';
+import { readJsonXLinesStream } from './stream';
+import type { ApiErrorSchemaOutput } from '../errors/ApiError';
+
+type NodeGlobal = {
+  process?: {
+    env?: Record<string, string | undefined>;
+  };
+};
+
+const isNodeEnvironment = (): boolean => {
+  const global = globalThis as NodeGlobal;
+
+  return typeof global.process?.env !== 'undefined';
+};
+
+const getNodeEnvVar = (key: string): string | undefined => {
+  if (!isNodeEnvironment()) {
+    return undefined;
+  }
+
+  const global = globalThis as NodeGlobal;
+
+  return global.process?.env?.[key];
+};
+
+const getAuth = (): CreateFetchOption['auth'] => {
+  const apiHasAuth = getNodeEnvVar('API_HAS_AUTH');
+  const apiUsername = getNodeEnvVar('API_USERNAME');
+  const apiPassword = getNodeEnvVar('API_PASSWORD');
+
+  if (apiHasAuth === 'true' && apiUsername && apiPassword) {
+    return {
+      type: 'Basic',
+      username: apiUsername,
+      password: apiPassword,
+    };
+  }
+
+  return undefined;
+};
+
+// Tries to gracefully format a value as a string, for printing in the logger
+const safeString = (value: unknown): string => {
+  try {
+    const string = typeof value === 'string' ? value : JSON.stringify(value);
+
+    if (!string) {
+      return String(value);
+    }
+
+    return string;
+  } catch {
+    return String(value);
+  }
+};
+
+// Captures any possible error from the fetch and turns it into an instance of our class, so all our errors are consistent
+export const normalizeError = async (
+  error: unknown,
+  options?: CreateFetchOption,
+): Promise<ApiError> => {
+  if (error instanceof ApiError) {
+    return error;
+  }
+
+  // Validation errors from schemas
+  if (error instanceof ValidationError) {
+    return new ApiError(
+      'Response schema validation failed.',
+      HttpStatus.BadRequest,
+      z.prettifyError(error),
+    );
+  }
+
+  // Upstream from better-fetch or when server responds with error
+  if (error instanceof BetterFetchError) {
+    // For some reason the library doesn't implement any functionality with the `errorSchema` option yet,
+    // so we do the validation ourselves (using the StandardSchemaV1 interface so it is zod-agnostic)
+    const parsed = await options?.errorSchema?.['~standard'].validate(error.error);
+
+    if (!parsed?.issues && parsed?.value) {
+      const { message, details } = parsed.value;
+
+      return new ApiError(message, error.status, details, {
+        // if we're reconstructing this error on the client from an error on the server, don't print the stack trace
+        rehydrated: typeof window !== 'undefined',
+      });
+    }
+
+    if (parsed?.issues) {
+      return new ApiError(error.statusText, error.status, z.prettifyError(parsed));
+    }
+
+    return new ApiError(
+      error.statusText,
+      error.status,
+      'Unknown error: validation returned empty result with no known issues reported.',
+    );
+  }
+
+  // Internal errors
+  if (error instanceof Error) {
+    return new ApiError(error.message, HttpStatus.InternalServerError, safeString(error.cause));
+  }
+
+  return ApiError.internalServerError('Unknown cause.');
+};
+
+// Override the options to enforce that an error schema is provided
+type CreateFetchOption = Omit<BetterFetchCreateFetchOption, 'errorSchema'> & {
+  errorSchema: StandardSchemaV1<unknown, ApiErrorSchemaOutput>;
+};
+
+// Override the schema options so we enforce a method is specified for each route
+type SchemaRoutes = Record<string, Omit<FetchSchema, 'method'> & { method: HttpMethods }>;
+
+/**
+ * Wrapper function around `@better-fetch/fetch` `createSchema` which creates a strict schema.
+ *
+ * A fetch schema is used to describe a list of routes, their HTTP method, inputs, and outputs.
+ *
+ * @param schema
+ * @param config
+ * @returns
+ */
+export const createSchema = <Routes extends SchemaRoutes>(schema: Routes) => {
+  return betterFetchCreateSchema(schema, {
+    strict: true,
+  });
+};
+
+// Utility type to merge two objects (used for merging schemas together)
+type MergeTwo<A, B> = {
+  [K in keyof A | keyof B]: K extends keyof B ? B[K] : K extends keyof A ? A[K] : never;
+};
+
+// Takes an array of schemas and merges all the routes together
+type MergeSchemasInner<T extends Schema[], Key extends keyof Schema> = T extends [
+  infer First extends Schema,
+  ...infer Rest extends Schema[],
+]
+  ? MergeTwo<First[Key], MergeSchemasInner<Rest, Key>>
+  : object;
+
+// Merges the schemas from an array, so multiple schemas can be provided.
+type MergeSchemas<T extends Schema[]> = {
+  schema: MergeSchemasInner<T, 'schema'>;
+  config: MergeSchemasInner<T, 'config'>;
+};
+
+// A custom plugin mainly used to fix a few bugs or add handling to extra content types, etc.
+const TOOLKIT_PLUGIN = {
+  id: 'toolkit-plugin',
+  name: 'Toolkit Plugin',
+  init: (url, options) => {
+    // If the body is `null` but no content type was supplied, it will try and detect it but error
+    // due to accessing a field on a null value. We handle this by setting the content type header
+    // if it doesn't exist and the body is null.
+    if (options?.body === null && !(options.headers as any)?.[Header.ContentType]) {
+      (options.headers as any)[Header.ContentType] = MimeType.Json;
+    }
+
+    return { url, options };
+  },
+  hooks: {
+    onRequest: (context) => {
+      // for some reason if you specify a JSON content type, better-fetch will not stringify the body
+      // but as we also have extra JSON mime types, we need to handle that
+      if (isJsonMimeType(context.headers.get(Header.ContentType))) {
+        context.body = JSON.stringify(context.body);
+      }
+
+      return context;
+    },
+    onResponse: (context) => {
+      if (context.response.headers.get(Header.ContentType)?.includes(MimeType.XJsonLines)) {
+        // `better-fetch` does not allow for handling of content types it doesn't know about, and it will
+        // always fall back to `.blob()`. We need to stream JSON X-Lines, so I do a hack to replace
+        // the blob function to return the streamed data instead. I am confident this is okay, as not only
+        // will it replace the function ONLY for this one content type, our custom plugin is always the LAST
+        // in the array, so it wouldn't mess with any other plugins that may use this.
+        (context.response as any).blob = async () => {
+          return await readJsonXLinesStream(context.response);
+        };
+      }
+
+      return context;
+    },
+  },
+} satisfies BetterFetchPlugin;
+
+/**
+ * Creates a fully typed and schema-validated fetch client by combining one or more `better-fetch` schemas.
+ *
+ * This wrapper extends the base `better-fetch` `createFetch` with:
+ * - **Automatic schema merging** — allows multiple schemas to be combined into one fetch instance.
+ * - **Enhanced error handling** — all thrown errors are normalized into consistent {@link ApiError} instances.
+ * - **Toolkit plugin** — adds extra handling for JSON content types, streaming JSON X-Lines responses,
+ *   and fixes some edge-case behaviors in the library.
+ * - **Automatic basic auth** — reads credentials from environment variables if available.
+ *
+ * The resulting client can be used exactly like a `better-fetch` instance, with full type inference
+ * for routes, inputs, and outputs derived from the merged schemas.
+ *
+ * @template Schemas - One or more `better-fetch` schemas to merge.
+ * @template Option - Configuration options, including enforced `errorSchema` type.
+ * @param schemas - An array of fetch schemas to merge into a single client.
+ * @param config - Optional configuration object passed to `better-fetch`, extended with defaults and plugins.
+ * @returns A `BetterFetch` instance with merged schema routes, automatic plugin registration, and normalized error handling.
+ *
+ * @see {@link https://github.com/better-fetch/better-fetch | better-fetch on GitHub}
+ */
+export const createFetch = <
+  Schemas extends Schema[],
+  Option extends CreateFetchOption = CreateFetchOption,
+>(
+  schemas: [...Schemas],
+  config?: Option,
+): BetterFetch<
+  Omit<Option, 'schema'> & {
+    schema: MergeSchemas<Schemas>;
+  }
+> => {
+  const mergedSchema = {
+    schema: Object.assign({}, ...schemas.map((s) => s.schema)),
+    config: Object.assign({}, ...schemas.map((s) => s.config)),
+  };
+
+  const instance = betterFetchCreateFetch({
+    schema: mergedSchema,
+    auth: getAuth(),
+    ...config,
+    plugins: [...(config?.plugins ?? []), TOOLKIT_PLUGIN],
+  });
+
+  // Wrap the fetcher to catch & normalize errors
+  return (async (...args) => {
+    try {
+      return await instance(...args);
+    } catch (err) {
+      throw await normalizeError(err, config);
+    }
+  }) as typeof instance;
+};

package/src/http/index.ts

@@ -0,0 +1,6 @@
+export * from './constants';
+export * from './logger';
+export * from './fetch';
+export * from './query';
+export * from './proxy';
+export * from './stream';