@hey-api/openapi-ts 0.80.18 → 0.81.1

package/dist/clients/core/serverSentEvents.ts

@@ -0,0 +1,235 @@
+import type { Config } from './types';
+
+export type ServerSentEventsOptions<TData = unknown> = Omit<
+  RequestInit,
+  'method'
+> &
+  Pick<Config, 'method' | 'responseTransformer' | 'responseValidator'> & {
+    /**
+     * Callback invoked when a network or parsing error occurs during streaming.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @param error The error that occurred.
+     */
+    onSseError?: (error: unknown) => void;
+    /**
+     * Callback invoked when an event is streamed from the server.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @param event Event streamed from the server.
+     * @returns Nothing (void).
+     */
+    onSseEvent?: (event: StreamEvent<TData>) => void;
+    /**
+     * Default retry delay in milliseconds.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @default 3000
+     */
+    sseDefaultRetryDelay?: number;
+    /**
+     * Maximum number of retry attempts before giving up.
+     */
+    sseMaxRetryAttempts?: number;
+    /**
+     * Maximum retry delay in milliseconds.
+     *
+     * Applies only when exponential backoff is used.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @default 30000
+     */
+    sseMaxRetryDelay?: number;
+    /**
+     * Optional sleep function for retry backoff.
+     *
+     * Defaults to using `setTimeout`.
+     */
+    sseSleepFn?: (ms: number) => Promise<void>;
+    url: string;
+  };
+
+export interface StreamEvent<TData = unknown> {
+  data: TData;
+  event?: string;
+  id?: string;
+  retry?: number;
+}
+
+export type ServerSentEventsResult<
+  TData = unknown,
+  TReturn = void,
+  TNext = unknown,
+> = {
+  stream: AsyncGenerator<
+    TData extends Record<string, unknown> ? TData[keyof TData] : TData,
+    TReturn,
+    TNext
+  >;
+};
+
+export const createSseClient = <TData = unknown>({
+  onSseError,
+  onSseEvent,
+  responseTransformer,
+  responseValidator,
+  sseDefaultRetryDelay,
+  sseMaxRetryAttempts,
+  sseMaxRetryDelay,
+  sseSleepFn,
+  url,
+  ...options
+}: ServerSentEventsOptions): ServerSentEventsResult<TData> => {
+  let lastEventId: string | undefined;
+
+  const sleep =
+    sseSleepFn ??
+    ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+
+  const createStream = async function* () {
+    let retryDelay: number = sseDefaultRetryDelay ?? 3000;
+    let attempt = 0;
+    const signal = options.signal ?? new AbortController().signal;
+
+    while (true) {
+      if (signal.aborted) break;
+
+      attempt++;
+
+      const headers =
+        options.headers instanceof Headers
+          ? options.headers
+          : new Headers(options.headers as Record<string, string> | undefined);
+
+      if (lastEventId !== undefined) {
+        headers.set('Last-Event-ID', lastEventId);
+      }
+
+      try {
+        const response = await fetch(url, { ...options, headers, signal });
+
+        if (!response.ok)
+          throw new Error(
+            `SSE failed: ${response.status} ${response.statusText}`,
+          );
+
+        if (!response.body) throw new Error('No body in SSE response');
+
+        const reader = response.body
+          .pipeThrough(new TextDecoderStream())
+          .getReader();
+
+        let buffer = '';
+
+        const abortHandler = () => {
+          try {
+            reader.cancel();
+          } catch {
+            // noop
+          }
+        };
+
+        signal.addEventListener('abort', abortHandler);
+
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += value;
+
+            const chunks = buffer.split('\n\n');
+            buffer = chunks.pop() ?? '';
+
+            for (const chunk of chunks) {
+              const lines = chunk.split('\n');
+              const dataLines: Array<string> = [];
+              let eventName: string | undefined;
+
+              for (const line of lines) {
+                if (line.startsWith('data:')) {
+                  dataLines.push(line.replace(/^data:\s*/, ''));
+                } else if (line.startsWith('event:')) {
+                  eventName = line.replace(/^event:\s*/, '');
+                } else if (line.startsWith('id:')) {
+                  lastEventId = line.replace(/^id:\s*/, '');
+                } else if (line.startsWith('retry:')) {
+                  const parsed = Number.parseInt(
+                    line.replace(/^retry:\s*/, ''),
+                    10,
+                  );
+                  if (!Number.isNaN(parsed)) {
+                    retryDelay = parsed;
+                  }
+                }
+              }
+
+              let data: unknown;
+              let parsedJson = false;
+
+              if (dataLines.length) {
+                const rawData = dataLines.join('\n');
+                try {
+                  data = JSON.parse(rawData);
+                  parsedJson = true;
+                } catch {
+                  data = rawData;
+                }
+              }
+
+              if (parsedJson) {
+                if (responseValidator) {
+                  await responseValidator(data);
+                }
+
+                if (responseTransformer) {
+                  data = await responseTransformer(data);
+                }
+              }
+
+              onSseEvent?.({
+                data,
+                event: eventName,
+                id: lastEventId,
+                retry: retryDelay,
+              });
+
+              if (dataLines.length) {
+                yield data as any;
+              }
+            }
+          }
+        } finally {
+          signal.removeEventListener('abort', abortHandler);
+          reader.releaseLock();
+        }
+
+        break; // exit loop on normal completion
+      } catch (error) {
+        // connection failed or aborted; retry after delay
+        onSseError?.(error);
+
+        if (
+          sseMaxRetryAttempts !== undefined &&
+          attempt >= sseMaxRetryAttempts
+        ) {
+          break; // stop after firing error
+        }
+
+        // exponential backoff: double retry each attempt, cap at 30s
+        const backoff = Math.min(
+          retryDelay * 2 ** (attempt - 1),
+          sseMaxRetryDelay ?? 30000,
+        );
+        await sleep(backoff);
+      }
+    }
+  };
+
+  const stream = createStream();
+
+  return { stream };
+};

package/dist/clients/core/types.ts

@@ -5,29 +5,36 @@ import type {
   QuerySerializerOptions,
 } from './bodySerializer';
 
-export interface Client<
+export type HttpMethod =
+  | 'connect'
+  | 'delete'
+  | 'get'
+  | 'head'
+  | 'options'
+  | 'patch'
+  | 'post'
+  | 'put'
+  | 'trace';
+
+export type Client<
   RequestFn = never,
   Config = unknown,
   MethodFn = never,
   BuildUrlFn = never,
-> {
+  SseFn = never,
+> = {
   /**
    * Returns the final request URL.
    */
   buildUrl: BuildUrlFn;
-  connect: MethodFn;
-  delete: MethodFn;
-  get: MethodFn;
   getConfig: () => Config;
-  head: MethodFn;
-  options: MethodFn;
-  patch: MethodFn;
-  post: MethodFn;
-  put: MethodFn;
   request: RequestFn;
   setConfig: (config: Config) => Config;
-  trace: MethodFn;
-}
+} & {
+  [K in HttpMethod]: MethodFn;
+} & ([SseFn] extends [never]
+    ? { sse?: never }
+    : { sse: { [K in HttpMethod]: SseFn } });
 
 export interface Config {
   /**
@@ -63,16 +70,7 @@ export interface Config {
    *
    * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
    */
-  method?:
-    | 'CONNECT'
-    | 'DELETE'
-    | 'GET'
-    | 'HEAD'
-    | 'OPTIONS'
-    | 'PATCH'
-    | 'POST'
-    | 'PUT'
-    | 'TRACE';
+  method?: Uppercase<HttpMethod>;
   /**
    * A function for serializing request query parameters. By default, arrays
    * will be exploded in form style, objects will be exploded in deepObject

package/dist/clients/core/utils.ts

@@ -0,0 +1,112 @@
+import type { QuerySerializer } from './bodySerializer';
+import {
+  type ArraySeparatorStyle,
+  serializeArrayParam,
+  serializeObjectParam,
+  serializePrimitiveParam,
+} from './pathSerializer';
+
+export interface PathSerializer {
+  path: Record<string, unknown>;
+  url: string;
+}
+
+export const PATH_PARAM_RE = /\{[^{}]+\}/g;
+
+export const defaultPathSerializer = ({ path, url: _url }: PathSerializer) => {
+  let url = _url;
+  const matches = _url.match(PATH_PARAM_RE);
+  if (matches) {
+    for (const match of matches) {
+      let explode = false;
+      let name = match.substring(1, match.length - 1);
+      let style: ArraySeparatorStyle = 'simple';
+
+      if (name.endsWith('*')) {
+        explode = true;
+        name = name.substring(0, name.length - 1);
+      }
+
+      if (name.startsWith('.')) {
+        name = name.substring(1);
+        style = 'label';
+      } else if (name.startsWith(';')) {
+        name = name.substring(1);
+        style = 'matrix';
+      }
+
+      const value = path[name];
+
+      if (value === undefined || value === null) {
+        continue;
+      }
+
+      if (Array.isArray(value)) {
+        url = url.replace(
+          match,
+          serializeArrayParam({ explode, name, style, value }),
+        );
+        continue;
+      }
+
+      if (typeof value === 'object') {
+        url = url.replace(
+          match,
+          serializeObjectParam({
+            explode,
+            name,
+            style,
+            value: value as Record<string, unknown>,
+            valueOnly: true,
+          }),
+        );
+        continue;
+      }
+
+      if (style === 'matrix') {
+        url = url.replace(
+          match,
+          `;${serializePrimitiveParam({
+            name,
+            value: value as string,
+          })}`,
+        );
+        continue;
+      }
+
+      const replaceValue = encodeURIComponent(
+        style === 'label' ? `.${value as string}` : (value as string),
+      );
+      url = url.replace(match, replaceValue);
+    }
+  }
+  return url;
+};
+
+export const getUrl = ({
+  baseUrl,
+  path,
+  query,
+  querySerializer,
+  url: _url,
+}: {
+  baseUrl?: string;
+  path?: Record<string, unknown>;
+  query?: Record<string, unknown>;
+  querySerializer: QuerySerializer;
+  url: string;
+}) => {
+  const pathUrl = _url.startsWith('/') ? _url : `/${_url}`;
+  let url = (baseUrl ?? '') + pathUrl;
+  if (path) {
+    url = defaultPathSerializer({ path, url });
+  }
+  let search = query ? querySerializer(query) : '';
+  if (search.startsWith('?')) {
+    search = search.substring(1);
+  }
+  if (search) {
+    url += `?${search}`;
+  }
+  return url;
+};

package/dist/clients/fetch/client.ts

@@ -1,4 +1,11 @@
-import type { Client, Config, ResolvedRequestOptions } from './types';
+import { createSseClient } from '../core/serverSentEvents';
+import type { HttpMethod } from '../core/types';
+import type {
+  Client,
+  Config,
+  RequestOptions,
+  ResolvedRequestOptions,
+} from './types';
 import {
   buildUrl,
   createConfig,
@@ -31,7 +38,7 @@ export const createClient = (config: Config = {}): Client => {
     ResolvedRequestOptions
   >();
 
-  const request: Client['request'] = async (options) => {
+  const beforeRequest = async (options: RequestOptions) => {
     const opts = {
       ..._config,
       ...options,
@@ -61,6 +68,13 @@ export const createClient = (config: Config = {}): Client => {
     }
 
     const url = buildUrl(opts);
+
+    return { opts, url };
+  };
+
+  const request: Client['request'] = async (options) => {
+    // @ts-expect-error
+    const { opts, url } = await beforeRequest(options);
     const requestInit: ReqInit = {
       redirect: 'follow',
       ...opts,
@@ -178,20 +192,47 @@ export const createClient = (config: Config = {}): Client => {
         };
   };
 
+  const makeMethodFn =
+    (method: Uppercase<HttpMethod>) => (options: RequestOptions) =>
+      request({ ...options, method });
+
+  const makeSseFn =
+    (method: Uppercase<HttpMethod>) => async (options: RequestOptions) => {
+      const { opts, url } = await beforeRequest(options);
+      return createSseClient({
+        ...opts,
+        body: opts.body as BodyInit | null | undefined,
+        headers: opts.headers as unknown as Record<string, string>,
+        method,
+        url,
+      });
+    };
+
   return {
     buildUrl,
-    connect: (options) => request({ ...options, method: 'CONNECT' }),
-    delete: (options) => request({ ...options, method: 'DELETE' }),
-    get: (options) => request({ ...options, method: 'GET' }),
+    connect: makeMethodFn('CONNECT'),
+    delete: makeMethodFn('DELETE'),
+    get: makeMethodFn('GET'),
     getConfig,
-    head: (options) => request({ ...options, method: 'HEAD' }),
+    head: makeMethodFn('HEAD'),
     interceptors,
-    options: (options) => request({ ...options, method: 'OPTIONS' }),
-    patch: (options) => request({ ...options, method: 'PATCH' }),
-    post: (options) => request({ ...options, method: 'POST' }),
-    put: (options) => request({ ...options, method: 'PUT' }),
+    options: makeMethodFn('OPTIONS'),
+    patch: makeMethodFn('PATCH'),
+    post: makeMethodFn('POST'),
+    put: makeMethodFn('PUT'),
     request,
     setConfig,
-    trace: (options) => request({ ...options, method: 'TRACE' }),
-  };
+    sse: {
+      connect: makeSseFn('CONNECT'),
+      delete: makeSseFn('DELETE'),
+      get: makeSseFn('GET'),
+      head: makeSseFn('HEAD'),
+      options: makeSseFn('OPTIONS'),
+      patch: makeSseFn('PATCH'),
+      post: makeSseFn('POST'),
+      put: makeSseFn('PUT'),
+      trace: makeSseFn('TRACE'),
+    },
+    trace: makeMethodFn('TRACE'),
+  } as Client;
 };

package/dist/clients/fetch/types.ts

@@ -1,4 +1,8 @@
 import type { Auth } from '../core/auth';
+import type {
+  ServerSentEventsOptions,
+  ServerSentEventsResult,
+} from '../core/serverSentEvents';
 import type {
   Client as CoreClient,
   Config as CoreConfig,
@@ -59,13 +63,22 @@ export interface Config<T extends ClientOptions = ClientOptions>
 }
 
 export interface RequestOptions<
+  TData = unknown,
   TResponseStyle extends ResponseStyle = 'fields',
   ThrowOnError extends boolean = boolean,
   Url extends string = string,
 > extends Config<{
-    responseStyle: TResponseStyle;
-    throwOnError: ThrowOnError;
-  }> {
+      responseStyle: TResponseStyle;
+      throwOnError: ThrowOnError;
+    }>,
+    Pick<
+      ServerSentEventsOptions<TData>,
+      | 'onSseError'
+      | 'onSseEvent'
+      | 'sseDefaultRetryDelay'
+      | 'sseMaxRetryAttempts'
+      | 'sseMaxRetryDelay'
+    > {
   /**
    * Any body that you want to add to your request.
    *
@@ -85,7 +98,7 @@ export interface ResolvedRequestOptions<
   TResponseStyle extends ResponseStyle = 'fields',
   ThrowOnError extends boolean = boolean,
   Url extends string = string,
-> extends RequestOptions<TResponseStyle, ThrowOnError, Url> {
+> extends RequestOptions<unknown, TResponseStyle, ThrowOnError, Url> {
   serializedBody?: string;
 }
 
@@ -146,17 +159,29 @@ type MethodFn = <
   ThrowOnError extends boolean = false,
   TResponseStyle extends ResponseStyle = 'fields',
 >(
-  options: Omit<RequestOptions<TResponseStyle, ThrowOnError>, 'method'>,
+  options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>,
 ) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
 
+type SseFn = <
+  TData = unknown,
+  TError = unknown,
+  ThrowOnError extends boolean = false,
+  TResponseStyle extends ResponseStyle = 'fields',
+>(
+  options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>,
+) => Promise<ServerSentEventsResult<TData, TError>>;
+
 type RequestFn = <
   TData = unknown,
   TError = unknown,
   ThrowOnError extends boolean = false,
   TResponseStyle extends ResponseStyle = 'fields',
 >(
-  options: Omit<RequestOptions<TResponseStyle, ThrowOnError>, 'method'> &
-    Pick<Required<RequestOptions<TResponseStyle, ThrowOnError>>, 'method'>,
+  options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'> &
+    Pick<
+      Required<RequestOptions<TData, TResponseStyle, ThrowOnError>>,
+      'method'
+    >,
 ) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
 
 type BuildUrlFn = <
@@ -170,7 +195,13 @@ type BuildUrlFn = <
   options: Pick<TData, 'url'> & Options<TData>,
 ) => string;
 
-export type Client = CoreClient<RequestFn, Config, MethodFn, BuildUrlFn> & {
+export type Client = CoreClient<
+  RequestFn,
+  Config,
+  MethodFn,
+  BuildUrlFn,
+  SseFn
+> & {
   interceptors: Middleware<Request, Response, unknown, ResolvedRequestOptions>;
 };
 
@@ -199,9 +230,10 @@ type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
 export type Options<
   TData extends TDataShape = TDataShape,
   ThrowOnError extends boolean = boolean,
+  TResponse = unknown,
   TResponseStyle extends ResponseStyle = 'fields',
 > = OmitKeys<
-  RequestOptions<TResponseStyle, ThrowOnError>,
+  RequestOptions<TResponse, TResponseStyle, ThrowOnError>,
   'body' | 'path' | 'query' | 'url'
 > &
   Omit<TData, 'url'>;
@@ -213,18 +245,22 @@ export type OptionsLegacyParser<
 > = TData extends { body?: any }
   ? TData extends { headers?: any }
     ? OmitKeys<
-        RequestOptions<TResponseStyle, ThrowOnError>,
+        RequestOptions<unknown, TResponseStyle, ThrowOnError>,
         'body' | 'headers' | 'url'
       > &
         TData
-    : OmitKeys<RequestOptions<TResponseStyle, ThrowOnError>, 'body' | 'url'> &
+    : OmitKeys<
+        RequestOptions<unknown, TResponseStyle, ThrowOnError>,
+        'body' | 'url'
+      > &
         TData &
-        Pick<RequestOptions<TResponseStyle, ThrowOnError>, 'headers'>
+        Pick<RequestOptions<unknown, TResponseStyle, ThrowOnError>, 'headers'>
   : TData extends { headers?: any }
     ? OmitKeys<
-        RequestOptions<TResponseStyle, ThrowOnError>,
+        RequestOptions<unknown, TResponseStyle, ThrowOnError>,
         'headers' | 'url'
       > &
         TData &
-        Pick<RequestOptions<TResponseStyle, ThrowOnError>, 'body'>
-    : OmitKeys<RequestOptions<TResponseStyle, ThrowOnError>, 'url'> & TData;
+        Pick<RequestOptions<unknown, TResponseStyle, ThrowOnError>, 'body'>
+    : OmitKeys<RequestOptions<unknown, TResponseStyle, ThrowOnError>, 'url'> &
+        TData;