@swapkit/api-sdk-typescript 1.0.3 → 1.1.0-nightly.20260701161042

package/src/core/pathSerializer.ts

@@ -25,7 +25,7 @@ interface SerializePrimitiveParam extends SerializePrimitiveOptions {
   value: string;
 }
 
-export const separatorArrayExplode = (style: ArraySeparatorStyle) => {
+export const separatorArrayExplode = (style: ArraySeparatorStyle): '.' | ';' | ',' | '&' => {
   switch (style) {
     case 'label':
       return '.';
@@ -38,7 +38,7 @@ export const separatorArrayExplode = (style: ArraySeparatorStyle) => {
   }
 };
 
-export const separatorArrayNoExplode = (style: ArraySeparatorStyle) => {
+export const separatorArrayNoExplode = (style: ArraySeparatorStyle): ',' | '|' | '%20' => {
   switch (style) {
     case 'form':
       return ',';
@@ -51,7 +51,7 @@ export const separatorArrayNoExplode = (style: ArraySeparatorStyle) => {
   }
 };
 
-export const separatorObjectExplode = (style: ObjectSeparatorStyle) => {
+export const separatorObjectExplode = (style: ObjectSeparatorStyle): '.' | ';' | ',' | '&' => {
   switch (style) {
     case 'label':
       return '.';
@@ -72,7 +72,7 @@ export const serializeArrayParam = ({
   value,
 }: SerializeOptions<ArraySeparatorStyle> & {
   value: unknown[];
-}) => {
+}): string => {
   if (!explode) {
     const joinedValues = (
       allowReserved ? value : value.map((v) => encodeURIComponent(v as string))
@@ -110,7 +110,7 @@ export const serializePrimitiveParam = ({
   allowReserved,
   name,
   value,
-}: SerializePrimitiveParam) => {
+}: SerializePrimitiveParam): string => {
   if (value === undefined || value === null) {
     return '';
   }
@@ -134,7 +134,7 @@ export const serializeObjectParam = ({
 }: SerializeOptions<ObjectSeparatorStyle> & {
   value: Record<string, unknown> | Date;
   valueOnly?: boolean;
-}) => {
+}): string => {
   if (value instanceof Date) {
     return valueOnly ? value.toISOString() : `${name}=${value.toISOString()}`;
   }

package/src/core/queryKeySerializer.ts

@@ -14,7 +14,7 @@ export type JsonValue =
 /**
  * Replacer that converts non-JSON values (bigint, Date, etc.) to safe substitutes.
  */
-export const queryKeyJsonReplacer = (_key: string, value: unknown) => {
+export const queryKeyJsonReplacer = (_key: string, value: unknown): unknown | undefined => {
   if (value === undefined || typeof value === 'function' || typeof value === 'symbol') {
     return undefined;
   }

package/src/core/serverSentEvents.ts

@@ -79,7 +79,7 @@ export type ServerSentEventsResult<TData = unknown, TReturn = void, TNext = unkn
   >;
 };
 
-export const createSseClient = <TData = unknown>({
+export function createSseClient<TData = unknown>({
   onRequest,
   onSseError,
   onSseEvent,
@@ -91,7 +91,7 @@ export const createSseClient = <TData = unknown>({
   sseSleepFn,
   url,
   ...options
-}: ServerSentEventsOptions): ServerSentEventsResult<TData> => {
+}: ServerSentEventsOptions): ServerSentEventsResult<TData> {
   let lastEventId: string | undefined;
 
   const sleep = sseSleepFn ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
@@ -155,8 +155,7 @@ export const createSseClient = <TData = unknown>({
             const { done, value } = await reader.read();
             if (done) break;
             buffer += value;
-            // Normalize line endings: CRLF -> LF, then CR -> LF
-            buffer = buffer.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+            buffer = buffer.replace(/\r\n?/g, '\n'); // normalize line endings
 
             const chunks = buffer.split('\n\n');
             buffer = chunks.pop() ?? '';
@@ -240,4 +239,4 @@ export const createSseClient = <TData = unknown>({
   const stream = createStream();
 
   return { stream };
-};
+}

package/src/core/types.ts

@@ -80,7 +80,7 @@ export interface Config {
   requestValidator?: (data: unknown) => Promise<unknown>;
   /**
    * A function transforming response data before it's returned. This is useful
-   * for post-processing data, e.g. converting ISO strings into Date objects.
+   * for post-processing data, e.g., converting ISO strings into Date objects.
    */
   responseTransformer?: (data: unknown) => Promise<unknown>;
   /**
@@ -91,6 +91,12 @@ export interface Config {
   responseValidator?: (data: unknown) => Promise<unknown>;
 }
 
+/**
+ * Arbitrary metadata passed through the `meta` request option.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface ClientMeta {}
+
 type IsExactlyNeverOrNeverUndefined<T> = [T] extends [never]
   ? true
   : [T] extends [never | undefined]

package/src/core/utils.ts

@@ -13,9 +13,9 @@ export interface PathSerializer {
   url: string;
 }
 
-export const PATH_PARAM_RE = /\{[^{}]+\}/g;
+export const PATH_PARAM_RE: RegExp = /\{[^{}]+\}/g;
 
-export const defaultPathSerializer = ({ path, url: _url }: PathSerializer) => {
+export const defaultPathSerializer = ({ path, url: _url }: PathSerializer): string => {
   let url = _url;
   const matches = _url.match(PATH_PARAM_RE);
   if (matches) {
@@ -94,7 +94,7 @@ export const getUrl = ({
   query?: Record<string, unknown>;
   querySerializer: QuerySerializer;
   url: string;
-}) => {
+}): string => {
   const pathUrl = _url.startsWith('/') ? _url : `/${_url}`;
   let url = (baseUrl ?? '') + pathUrl;
   if (path) {
@@ -114,7 +114,7 @@ export function getValidRequestBody(options: {
   body?: unknown;
   bodySerializer?: BodySerializer | null;
   serializedBody?: unknown;
-}) {
+}): unknown {
   const hasBody = options.body !== undefined;
   const isSerializedBody = hasBody && options.bodySerializer;
 
@@ -126,7 +126,7 @@ export function getValidRequestBody(options: {
       return hasSerializedBody ? options.serializedBody : null;
     }
 
-    // not all clients implement a serializedBody property (i.e. client-axios)
+    // not all clients implement a serializedBody property (i.e., client-axios)
     return options.body !== '' ? options.body : null;
   }
 

package/src/http/client.ts

@@ -31,20 +31,24 @@ export const createClient = (config: Config = {}): Client => {
 
   const interceptors = createInterceptors<Request, Response, unknown, ResolvedRequestOptions>();
 
-  const beforeRequest = async (options: RequestOptions) => {
+  const beforeRequest = async <
+    TData = unknown,
+    TResponseStyle extends 'data' | 'fields' = 'fields',
+    ThrowOnError extends boolean = boolean,
+    Url extends string = string,
+  >(
+    options: RequestOptions<TData, TResponseStyle, ThrowOnError, Url>,
+  ) => {
     const opts = {
       ..._config,
       ...options,
       fetch: options.fetch ?? _config.fetch ?? globalThis.fetch,
       headers: mergeHeaders(_config.headers, options.headers),
-      serializedBody: undefined,
+      serializedBody: undefined as string | undefined,
     };
 
     if (opts.security) {
-      await setAuthParams({
-        ...opts,
-        security: opts.security,
-      });
+      await setAuthParams(opts);
     }
 
     if (opts.requestValidator) {
@@ -52,7 +56,7 @@ export const createClient = (config: Config = {}): Client => {
     }
 
     if (opts.body !== undefined && opts.bodySerializer) {
-      opts.serializedBody = opts.bodySerializer(opts.body);
+      opts.serializedBody = opts.bodySerializer(opts.body) as string | undefined;
     }
 
     // remove Content-Type header if body is empty to avoid sending invalid requests
@@ -60,178 +64,162 @@ export const createClient = (config: Config = {}): Client => {
       opts.headers.delete('Content-Type');
     }
 
-    const url = buildUrl(opts);
+    const resolvedOpts = opts as typeof opts &
+      ResolvedRequestOptions<TResponseStyle, ThrowOnError, Url>;
+    const url = buildUrl(resolvedOpts);
 
-    return { opts, url };
+    return { opts: resolvedOpts, url };
   };
 
   const request: Client['request'] = async (options) => {
-    // @ts-expect-error
-    const { opts, url } = await beforeRequest(options);
-    const requestInit: ReqInit = {
-      redirect: 'follow',
-      ...opts,
-      body: getValidRequestBody(opts),
-    };
-
-    let request = new Request(url, requestInit);
+    const throwOnError = options.throwOnError ?? _config.throwOnError;
+    const responseStyle = options.responseStyle ?? _config.responseStyle;
 
-    for (const fn of interceptors.request.fns) {
-      if (fn) {
-        request = await fn(request, opts);
-      }
-    }
-
-    // fetch must be assigned here, otherwise it would throw the error:
-    // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
-    const _fetch = opts.fetch!;
-    let response: Response;
+    let request: Request | undefined;
+    let response: Response | undefined;
 
     try {
-      response = await _fetch(request);
-    } catch (error) {
-      // Handle fetch exceptions (AbortError, network errors, etc.)
-      let finalError = error;
+      const { opts, url } = await beforeRequest(options);
+      const requestInit: ReqInit = {
+        redirect: 'follow',
+        ...opts,
+        body: getValidRequestBody(opts),
+      };
 
-      for (const fn of interceptors.error.fns) {
+      request = new Request(url, requestInit);
+
+      for (const fn of interceptors.request.fns) {
         if (fn) {
-          finalError = (await fn(error, undefined as any, request, opts)) as unknown;
+          request = await fn(request, opts);
         }
       }
 
-      finalError = finalError || ({} as unknown);
+      // fetch must be assigned here, otherwise it would throw the error:
+      // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
+      const _fetch = opts.fetch!;
 
-      if (opts.throwOnError) {
-        throw finalError;
-      }
-
-      // Return error response
-      return opts.responseStyle === 'data'
-        ? undefined
-        : {
-            error: finalError,
-            request,
-            response: undefined as any,
-          };
-    }
+      response = await _fetch(request);
 
-    for (const fn of interceptors.response.fns) {
-      if (fn) {
-        response = await fn(response, request, opts);
+      for (const fn of interceptors.response.fns) {
+        if (fn) {
+          response = await fn(response, request, opts);
+        }
       }
-    }
-
-    const result = {
-      request,
-      response,
-    };
 
-    if (response.ok) {
-      const parseAs =
-        (opts.parseAs === 'auto'
-          ? getParseAs(response.headers.get('Content-Type'))
-          : opts.parseAs) ?? 'json';
+      const result = {
+        request,
+        response,
+      };
+
+      if (response.ok) {
+        const parseAs =
+          (opts.parseAs === 'auto'
+            ? getParseAs(response.headers.get('Content-Type'))
+            : opts.parseAs) ?? 'json';
+
+        if (response.status === 204 || response.headers.get('Content-Length') === '0') {
+          let emptyData: any;
+          switch (parseAs) {
+            case 'arrayBuffer':
+            case 'blob':
+            case 'text':
+              emptyData = await response[parseAs]();
+              break;
+            case 'formData':
+              emptyData = new FormData();
+              break;
+            case 'stream':
+              emptyData = response.body;
+              break;
+            case 'json':
+            default:
+              emptyData = {};
+              break;
+          }
+          return opts.responseStyle === 'data'
+            ? emptyData
+            : {
+                data: emptyData,
+                ...result,
+              };
+        }
 
-      if (response.status === 204 || response.headers.get('Content-Length') === '0') {
-        let emptyData: any;
+        let data: any;
         switch (parseAs) {
           case 'arrayBuffer':
           case 'blob':
+          case 'formData':
           case 'text':
-            emptyData = await response[parseAs]();
+            data = await response[parseAs]();
             break;
-          case 'formData':
-            emptyData = new FormData();
+          case 'json': {
+            // Some servers return 200 with no Content-Length and empty body.
+            // response.json() would throw; read as text and parse if non-empty.
+            const text = await response.text();
+            data = text ? JSON.parse(text) : {};
             break;
+          }
           case 'stream':
-            emptyData = response.body;
-            break;
-          case 'json':
-          default:
-            emptyData = {};
-            break;
+            return opts.responseStyle === 'data'
+              ? response.body
+              : {
+                  data: response.body,
+                  ...result,
+                };
+        }
+
+        if (parseAs === 'json') {
+          if (opts.responseValidator) {
+            await opts.responseValidator(data);
+          }
+
+          if (opts.responseTransformer) {
+            data = await opts.responseTransformer(data);
+          }
         }
+
         return opts.responseStyle === 'data'
-          ? emptyData
+          ? data
           : {
-              data: emptyData,
+              data,
               ...result,
             };
       }
 
-      let data: any;
-      switch (parseAs) {
-        case 'arrayBuffer':
-        case 'blob':
-        case 'formData':
-        case 'text':
-          data = await response[parseAs]();
-          break;
-        case 'json': {
-          // Some servers return 200 with no Content-Length and empty body.
-          // response.json() would throw; read as text and parse if non-empty.
-          const text = await response.text();
-          data = text ? JSON.parse(text) : {};
-          break;
-        }
-        case 'stream':
-          return opts.responseStyle === 'data'
-            ? response.body
-            : {
-                data: response.body,
-                ...result,
-              };
+      const textError = await response.text();
+      let jsonError: unknown;
+
+      try {
+        jsonError = JSON.parse(textError);
+      } catch {
+        // noop
       }
 
-      if (parseAs === 'json') {
-        if (opts.responseValidator) {
-          await opts.responseValidator(data);
-        }
+      throw jsonError ?? textError;
+    } catch (error) {
+      let finalError = error;
 
-        if (opts.responseTransformer) {
-          data = await opts.responseTransformer(data);
+      for (const fn of interceptors.error.fns) {
+        if (fn) {
+          finalError = await fn(finalError, response, request, options as ResolvedRequestOptions);
         }
       }
 
-      return opts.responseStyle === 'data'
-        ? data
-        : {
-            data,
-            ...result,
-          };
-    }
+      finalError = finalError || {};
 
-    const textError = await response.text();
-    let jsonError: unknown;
-
-    try {
-      jsonError = JSON.parse(textError);
-    } catch {
-      // noop
-    }
-
-    const error = jsonError ?? textError;
-    let finalError = error;
-
-    for (const fn of interceptors.error.fns) {
-      if (fn) {
-        finalError = (await fn(error, response, request, opts)) as string;
+      if (throwOnError) {
+        throw finalError;
       }
-    }
-
-    finalError = finalError || ({} as string);
 
-    if (opts.throwOnError) {
-      throw finalError;
+      // TODO: we probably want to return error and improve types
+      return responseStyle === 'data'
+        ? undefined
+        : {
+            error: finalError,
+            request,
+            response,
+          };
     }
-
-    // TODO: we probably want to return error and improve types
-    return opts.responseStyle === 'data'
-      ? undefined
-      : {
-          error: finalError,
-          ...result,
-        };
   };
 
   const makeMethodFn = (method: Uppercase<HttpMethod>) => (options: RequestOptions) =>
@@ -242,7 +230,6 @@ export const createClient = (config: Config = {}): Client => {
     return createSseClient({
       ...opts,
       body: opts.body as BodyInit | null | undefined,
-      headers: opts.headers as unknown as Record<string, string>,
       method,
       onRequest: async (url, init) => {
         let request = new Request(url, init);
@@ -258,8 +245,10 @@ export const createClient = (config: Config = {}): Client => {
     });
   };
 
+  const _buildUrl: Client['buildUrl'] = (options) => buildUrl({ ..._config, ...options });
+
   return {
-    buildUrl,
+    buildUrl: _buildUrl,
     connect: makeMethodFn('CONNECT'),
     delete: makeMethodFn('DELETE'),
     get: makeMethodFn('GET'),

package/src/http/index.ts

@@ -9,6 +9,8 @@ export {
 } from '../core/bodySerializer';
 export { buildClientParams } from '../core/params';
 export { serializeQueryKeyValue } from '../core/queryKeySerializer';
+export type { ServerSentEventsResult } from '../core/serverSentEvents';
+export type { ClientMeta } from '../core/types';
 export { createClient } from './client';
 export type {
   Client,

package/src/http/types.ts

@@ -93,6 +93,7 @@ export interface ResolvedRequestOptions<
   ThrowOnError extends boolean = boolean,
   Url extends string = string,
 > extends RequestOptions<unknown, TResponseStyle, ThrowOnError, Url> {
+  headers: Headers;
   serializedBody?: string;
 }
 
@@ -126,8 +127,10 @@ export type RequestResult<
                 error: TError extends Record<string, unknown> ? TError[keyof TError] : TError;
               }
           ) & {
-            request: Request;
-            response: Response;
+            /** request may be undefined, because error may be from building the request object itself */
+            request?: Request;
+            /** response may be undefined, because error may be from building the request object itself or from a network error */
+            response?: Response;
           }
     >;
 
@@ -148,12 +151,13 @@ type MethodFn = <
 
 type SseFn = <
   TData = unknown,
-  TError = unknown,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  _TError = unknown,
   ThrowOnError extends boolean = false,
   TResponseStyle extends ResponseStyle = 'fields',
 >(
-  options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>,
-) => Promise<ServerSentEventsResult<TData, TError>>;
+  options: Omit<RequestOptions<never, TResponseStyle, ThrowOnError>, 'method'>,
+) => Promise<ServerSentEventsResult<TData>>;
 
 type RequestFn = <
   TData = unknown,
@@ -190,7 +194,7 @@ export type Client = CoreClient<RequestFn, Config, MethodFn, BuildUrlFn, SseFn>
  */
 export type CreateClientConfig<T extends ClientOptions = ClientOptions> = (
   override?: Config<ClientOptions & T>,
-) => Config<Required<ClientOptions> & T> | Promise<Config<Required<ClientOptions> & T>>;
+) => Config<Required<ClientOptions> & T>;
 
 export interface TDataShape {
   body?: unknown;

package/src/http/utils.ts

@@ -14,8 +14,8 @@ import type { Client, ClientOptions, Config, RequestOptions } from './types';
 export const createQuerySerializer = <T = unknown>({
   parameters = {},
   ...args
-}: QuerySerializerOptions = {}) => {
-  const querySerializer = (queryParams: T) => {
+}: QuerySerializerOptions = {}): ((queryParams: T) => string) => {
+  const querySerializer = (queryParams: T): string => {
     const search: string[] = [];
     if (queryParams && typeof queryParams === 'object') {
       for (const name in queryParams) {
@@ -118,14 +118,12 @@ const checkForExistence = (
   return false;
 };
 
-export const setAuthParams = async ({
-  security,
-  ...options
-}: Pick<Required<RequestOptions>, 'security'> &
-  Pick<RequestOptions, 'auth' | 'query'> & {
+export async function setAuthParams(
+  options: Pick<RequestOptions, 'auth' | 'query' | 'security'> & {
     headers: Headers;
-  }) => {
-  for (const auth of security) {
+  },
+): Promise<void> {
+  for (const auth of options.security ?? []) {
     if (checkForExistence(options, auth.name)) {
       continue;
     }
@@ -154,7 +152,7 @@ export const setAuthParams = async ({
         break;
     }
   }
-};
+}
 
 export const buildUrl: Client['buildUrl'] = (options) =>
   getUrl({
@@ -204,7 +202,7 @@ export const mergeHeaders = (
           mergedHeaders.append(key, v as string);
         }
       } else if (value !== undefined) {
-        // assume object headers are meant to be JSON stringified, i.e. their
+        // assume object headers are meant to be JSON stringified, i.e., their
         // content value in OpenAPI specification is 'application/json'
         mergedHeaders.set(
           key,
@@ -218,8 +216,10 @@ export const mergeHeaders = (
 
 type ErrInterceptor<Err, Res, Req, Options> = (
   error: Err,
-  response: Res,
-  request: Req,
+  /** response may be undefined due to a network error where no response object is produced */
+  response: Res | undefined,
+  /** request may be undefined, because error may be from building the request object itself */
+  request: Req | undefined,
   options: Options,
 ) => Err | Promise<Err>;