@stack-spot/portal-network 0.1.0 → 0.3.0

package/src/network/NetworkClient.ts

@@ -1,17 +1,36 @@
-import { mergeHeaders } from '@oazapfts/runtime/headers'
 import { AuthenticationError } from '@stack-spot/auth'
 import { requestPermission } from '@stack-spot/opa'
-import { Env, HTTPMethod, RequestOptions, RequestWithBody, SessionManager } from './types'
+import { Env, HTTPMethod, SessionManager } from './types'
 
-export class NetworkClient {
+/**
+ * A set of methods for performing network requests to an API.
+ * 
+ * The requests are authenticated unless there's no session available.
+ * 
+ * In order for a network client to work properly, the general setup for the class `NetworkClient` must be made before any request is
+ * attempted:
+ * 
+ * ```
+ * NetworkClient.setup(mySessionManager, currentEnv)
+ * ```
+ */
+export abstract class NetworkClient {
   private baseURL: Record<Env, string>
   private static sessionManager?: SessionManager
   private static env?: Env
 
+  /**
+   * @param baseURL An object with the keys "dev", "stg" and "prd". The values must be the url for each of these environments.
+   */
   constructor(baseURL: Record<Env, string>) {
     this.baseURL = baseURL
   }
 
+  /**
+   * Sets up all network clients. Must be called before attempting to make any request.
+   * @param sessionManager An object with functions capable of checking, retrieving and ending the current session.
+   * @param env The environment to send the requests to.
+   */
   static setup(sessionManager: SessionManager, env: Env) {
     NetworkClient.sessionManager = sessionManager
     NetworkClient.env = env
@@ -21,6 +40,11 @@ export class NetworkClient {
     return new Error('Please, call "NetworkClient.setup(sessionManager, env)" before attempting to make a request.')
   }
 
+  /**
+   * Builds a URL with the `baseUrl` of this network client and the `path` passed as parameter. 
+   * @param path the path to the resource.
+   * @returns a full URL.
+   */
   protected resolveURL(path: string) {
     if (!NetworkClient.env) throw this.uninitializedError()
     // paths must not start with "/", otherwise, the base url will not be fully appended to it.
@@ -30,6 +54,13 @@ export class NetworkClient {
     return new URL(fixedPath, fixedBaseUrl)
   }
 
+  /**
+   * Verifies if the current user is allowed to send the given request.
+   * @param method the request's method.
+   * @param path the path to the resource.
+   * @param body the request's body.
+   * @returns a promise that resolves to true if it's allowed or false otherwise.
+   */
   protected requestPermission(method: HTTPMethod, path: string, body?: string | object): Promise<boolean> {
     return requestPermission(method, this.resolveURL(path).toString(), body)
   }
@@ -40,52 +71,33 @@ export class NetworkClient {
     return sessionManager
   }
 
-  private sendRequest(path: string, method: HTTPMethod, request?: RequestWithBody): Promise<Response> {
+  /**
+   * Makes a request (same signature as `globalThis.fetch`). This request will prepend the base url to the url and, if there's an active
+   * session, include authentication headers.
+   * @param input the url or request object.
+   * @param init the fetch options.
+   * @returns a promise with the Response.
+   */
+  protected fetch(input: string | URL | Request, init?: RequestInit): Promise<Response> {
     const sessionManager = this.getSessionManager()
-    const url = this.resolveURL(path)
+    let inputWithBaseUrl: string | URL | Request = ''
+    if (typeof input === 'string') inputWithBaseUrl = this.resolveURL(input)
+    else if (input instanceof URL) inputWithBaseUrl = this.resolveURL(input.toString())
+    else inputWithBaseUrl = { ...input, url: this.resolveURL(input.url).toString() }
+    // some APIs throw errors if the method is lowercase, the following line prevents it
+    if (init?.method) init.method = init.method.toUpperCase()
     try {
-      if (request?.params) {
-        Object.keys(request.params).forEach((key) => {
-          const value = request?.params?.[key]
-          if (value !== undefined) url.searchParams.set(key, value)
-        })
-      }
-      const isFormData = request?.body instanceof FormData
-      const isJsonContent = (typeof request?.body === 'object') && !isFormData
-      const body = isJsonContent ? JSON.stringify(request.body) : request?.body as string | FormData
-      const defaultHeaders: Record<string, string> = isJsonContent ? { 'Content-Type': 'application/json' } : {}
-      const headers = mergeHeaders(defaultHeaders, request?.headers)
-      return (
-        sessionManager.hasSession()
-          ? sessionManager.getSession().fetch(url, { method: method.toUpperCase(), headers, body })
-          : fetch(url, { method: method.toUpperCase(), headers, body })
-      )
+      return sessionManager.hasSession() ? sessionManager.getSession().fetch(inputWithBaseUrl, init) : fetch(inputWithBaseUrl, init)
     } catch (error) {
       if (error instanceof AuthenticationError) sessionManager.endSession()
       throw error
     }
   }
 
-  protected get<T>(path: string, request?: RequestOptions): Promise<T> {
-    return this.sendRequest(path, 'get', request) as Promise<T>
-  }
-
-  protected post<T>(path: string, request?: RequestWithBody): Promise<T> {
-    return this.sendRequest(path, 'post', request) as Promise<T>
-  }
-
-  protected put<T>(path: string, request?: RequestWithBody): Promise<T> {
-    return this.sendRequest(path, 'put', request) as Promise<T>
-  }
-
-  protected patch<T>(path: string, request?: RequestWithBody): Promise<T> {
-    return this.sendRequest(path, 'patch', request) as Promise<T>
-  }
-
-  protected delete<T>(path: string, request?: RequestWithBody): Promise<T> {
-    return this.sendRequest(path, 'delete', request) as Promise<T>
-  }
-
+  /**
+   * Checks whether or not the current account is freemium.
+   * @returns true if it's a freemium account, false otherwise.
+   */
   protected isFreemium() {
     const sessionManager = this.getSessionManager()
     return sessionManager.hasSession() && !!sessionManager.getSession().getTokenData().freemium_status

package/src/network/ReactQueryNetworkClient.ts

@@ -2,39 +2,31 @@
 
 import { Defaults, HttpError, RequestOpts } from '@oazapfts/runtime'
 import { StackspotAPIError } from '../error/StackspotAPIError'
+import { AutoInfiniteQuery } from './AutoInfiniteQuery'
 import { AutoMutation } from './AutoMutation'
 import { AutoQuery } from './AutoQuery'
+import { ManualInfiniteQuery } from './ManualInfiniteQuery'
 import { ManualMutation } from './ManualMutation'
 import { ManualQuery } from './ManualQuery'
 import { NetworkClient } from './NetworkClient'
-import { Env, HTTPMethod, MutationObject, OperationConfig, OperationObject, QueryObject } from './types'
+import { Env, HTTPMethod, InfiniteQueryConfig, InfiniteQueryObject, InfiniteQueryOptions, MutationObject, OperationConfig, OperationObject, QueryObject } from './types'
 
 const DUMMY_ULID = '01HSTZ5471CBG4AW9BFJ0VTVG9'
 const PERMISSION_ERROR = 'permission-error'
+export const DEFAULT_PAGE_SIZE = 20
 
+/**
+ * A Network Client that uses oazapfts for making requests and React Query for managing responses.
+ */
 export abstract class ReactQueryNetworkClient extends NetworkClient {
+  /**
+   * @param baseURL An object with the keys "dev", "stg" and "prd". The values must be the url for each of these environments.
+   * @param defaults the `default` object of the API this client is for (provided by the code generated by oazapfts).
+   */
   constructor(baseURL: Record<Env, string>, defaults: Defaults<any>) {
     super(baseURL)
     defaults.baseUrl = ''
-    // eslint-disable-next-line arrow-body-style
-    defaults.fetch = (...args) => {
-      return this.#onFetch(...args)
-    }
-  }
-
-  #getMappedHeaders(headers: HeadersInit | undefined) {
-    if (!headers) return undefined
-    if (headers instanceof Headers) {
-      const headersMap: Record<string, string> = {}
-      headers.forEach((value, key) => headersMap[key] = value)
-      return headersMap
-    }
-    if (Array.isArray(headers)) {
-      const headersMap: Record<string, string> = {}
-      headers.forEach(([key, value]) => headersMap[key] = value)
-      return headersMap
-    }
-    return headers
+    defaults.fetch = (...args) => this.fetch(...args)
   }
 
   #parseErrorData(error: HttpError) {
@@ -73,13 +65,10 @@ export abstract class ReactQueryNetworkClient extends NetworkClient {
     }
   )
 
-  #onFetch(input: string | URL | Request, init?: RequestInit | undefined): Promise<Response> {
-    const [path, method, body, headers] = input instanceof Request
-      ? [input.url, input.method as HTTPMethod, input.body, input.headers]
-      : [`${input}`, (init?.method?.toLowerCase() || 'get') as HTTPMethod, init?.body, init?.headers]
-    return this[method](path, { body: body as any, headers: this.#getMappedHeaders(headers) })
-  }
-
+  /**
+   * Receives an HttpError and returns a StackspotAPIError.
+   * @param error the original HttpError created by oazapfts.
+   */
   protected abstract buildStackSpotError(error: HttpError): StackspotAPIError
 
   async #onFetchPermission(input: string | URL | Request, init?: RequestInit | undefined): Promise<Response> {
@@ -97,15 +86,27 @@ export abstract class ReactQueryNetworkClient extends NetworkClient {
     }
   }
 
-  protected query<Args extends [opts?: RequestOpts] | [variables: Record<string, any>, opts?: RequestOpts], Result>(
-    fn: (...args: Args) => Promise<Result>
-  ): Args extends [variables: infer Variables, opts?: RequestOpts] ? QueryObject<Variables, Result> : QueryObject<void, Result>
+  /**
+   * Builds a query manually by using a configuration object. 
+   * @param config the configuration object containing the name, a request function and a permission function.
+   */
   protected query<Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result>(
     config: OperationConfig<Args, Result>,
   ): QueryObject<Args extends [AbortSignal] ? void : Args[1], Result>
+  /**
+   * Builds a query manually by using a configuration object. 
+   * @param config the configuration object containing the name and a request function. 
+   */
   protected query<Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result>(
     config: Omit<OperationConfig<Args, Result>, 'permission'>,
   ): Omit<QueryObject<Args extends [AbortSignal] ? void : Args[1], Result>, 'isAllowed' | 'useAllowed' | 'getPermissionKey'>
+  /**
+   * Builds a query automatically by using a function generated by oazapfts. 
+   * @param fn the oazapfts function.
+   */
+  protected query<Args extends [opts?: RequestOpts] | [variables: Record<string, any>, opts?: RequestOpts], Result>(
+    fn: (...args: Args) => Promise<Result>
+  ): Args extends [variables: infer Variables, opts?: RequestOpts] ? QueryObject<Variables, Result> : QueryObject<void, Result>
   protected query(fnOrConfig: any): QueryObject<any, any> {
     return typeof fnOrConfig === 'function'
       ? new AutoQuery(
@@ -124,15 +125,112 @@ export abstract class ReactQueryNetworkClient extends NetworkClient {
       })
   }
 
-  protected mutation<Args extends [opts?: RequestOpts] | [variables: Record<string, any>, opts?: RequestOpts], Result>(
-    fn: (...args: Args) => Promise<Result>,
-  ): Args extends [variables: infer Variables, opts?: RequestOpts] ? MutationObject<Variables, Result> : MutationObject<void, Result>
+  /**
+   * Builds a query manually by using a configuration object. 
+   * @param config the configuration object containing the name, a request function and a permission function.
+   */
+  protected infiniteQuery<
+    Variables extends Record<string, any>,
+    Result,
+    PageParamName extends keyof Variables,
+    Accumulator extends keyof Result | '',
+  >(config: InfiniteQueryConfig<Variables, Result, PageParamName, Accumulator>): InfiniteQueryObject<Variables, Result, Accumulator>
+  /**
+   * Builds a query manually by using a configuration object. 
+   * @param config the configuration object containing the name and a request function. 
+   */
+  protected infiniteQuery<
+    Variables extends Record<string, any>,
+    Result,
+    PageParamName extends keyof Variables,
+    Accumulator extends keyof Result | '',
+  >(
+    config: Omit<InfiniteQueryConfig<Variables, Result, PageParamName, Accumulator>, 'permission'>,
+  ): Omit<InfiniteQueryObject<Variables, Result, Accumulator>, 'isAllowed' | 'useAllowed' | 'getPermissionKey'>
+  /**
+   * Builds a query automatically by using a function generated by oazapfts. 
+   * @param fn the oazapfts function.
+   * @param options the configuration for the infinite query.
+   */
+  protected infiniteQuery<
+    Variables extends Record<string, any>,
+    Result,
+    PageParamName extends keyof Variables,
+    Accumulator extends keyof Result,
+  >(
+    fn: (variables: Variables, opts?: RequestOpts) => Promise<Result>,
+    options: Partial<InfiniteQueryOptions<Variables, Result, PageParamName, Accumulator>>,
+  ): InfiniteQueryObject<Variables, Result, Accumulator>
+  /**
+   * Builds a query automatically by using a function generated by oazapfts with the variables `page` and `size`. 
+   * @param fn the oazapfts function that returns an array.
+   * @param options optional configuration for the infinite query. By default, it will use the variables page and size of the function
+   * passed in the first parameter.
+   */
+  protected infiniteQuery<
+    Variables extends { page?: number, size?: number },
+    Result extends any[],
+    PageParamName extends keyof Variables = 'page',
+    Accumulator extends keyof Result | '' = '',
+  >(
+    fn: (variables: Variables, opts?: RequestOpts) => Promise<Result>,
+    options?: Partial<InfiniteQueryOptions<Variables, Result, PageParamName, Accumulator>>,
+  ): InfiniteQueryObject<Variables, Result, Accumulator>
+  protected infiniteQuery(
+    fnOrConfig: any, options?: Partial<InfiniteQueryOptions<any, any, any, any>>,
+  ): InfiniteQueryObject<any, any, any> {
+    return typeof fnOrConfig === 'function'
+      ? new AutoInfiniteQuery(
+        {
+          apiName: this.constructor.name,
+          fn: fnOrConfig,
+          onFetchPermission: (...args) => this.#onFetchPermission(...args),
+          transformError: error => this.#transformError(error),
+        },
+        {
+          accumulator: options?.accumulator ?? '',
+          pageParamName: options?.pageParamName ?? 'page',
+          initialPageParam: options?.initialPageParam ?? 1,
+          defaultVariables: options?.defaultVariables ?? { size: DEFAULT_PAGE_SIZE },
+          getNextPageParam: options?.getNextPageParam ?? (({ variables, lastPage, lastPageParam }) => {
+            const size = variables.size ?? 1
+            const isLastPageTheLast = lastPage && (
+              (Array.isArray(lastPage) && lastPage.length < size)
+              || (options?.accumulator !== undefined && options?.accumulator !== '' && lastPage[options?.accumulator]?.length < size)
+            )
+            return isLastPageTheLast ? undefined : lastPageParam + 1
+          }),
+        },
+      )
+      : new ManualInfiniteQuery({
+        ...fnOrConfig,
+        apiName: this.constructor.name,
+        request: this.#withErrorTreatment(fnOrConfig.request),
+        permission: fnOrConfig.permission ? this.#withErrorTreatment(fnOrConfig.permission) : undefined,
+      })
+  }
+
+  /**
+   * Builds a mutation manually by using a configuration object. 
+   * @param config the configuration object containing the name, a request function and a permission function.
+   */
   protected mutation<Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result>(
     config: OperationConfig<Args, Result>,
   ): MutationObject<Args extends [AbortSignal] ? void : Args[1], Result>
+  /**
+   * Builds a mutation manually by using a configuration object. 
+   * @param config the configuration object containing the name and a request function. 
+   */
   protected mutation<Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result>(
     config: Omit<OperationConfig<Args, Result>, 'permission'>,
   ): Omit<MutationObject<Args extends [AbortSignal] ? void : Args[1], Result>, keyof OperationObject<any>>
+  /**
+   * Builds a mutation automatically by using a function generated by oazapfts. 
+   * @param fn the oazapfts function.
+   */
+  protected mutation<Args extends [opts?: RequestOpts] | [variables: Record<string, any>, opts?: RequestOpts], Result>(
+    fn: (...args: Args) => Promise<Result>,
+  ): Args extends [variables: infer Variables, opts?: RequestOpts] ? MutationObject<Variables, Result> : MutationObject<void, Result>
   protected mutation(fnOrConfig: any): MutationObject<any, any> {
     if (typeof fnOrConfig === 'function') {
       return new AutoMutation(

package/src/network/react-query-client.ts

@@ -1,3 +1,6 @@
 import { QueryClient } from '@tanstack/react-query'
 
+/**
+ * The global, unique, Query Client for React Query.
+ */
 export const queryClient = new QueryClient({ defaultOptions: { queries: { refetchOnWindowFocus: false, retry: 3 } } })

package/src/network/types.ts

@@ -1,6 +1,6 @@
 import type { RequestOpts } from '@oazapfts/runtime'
 import { Session } from '@stack-spot/auth'
-import { MutateOptions, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query'
+import { InfiniteData, MutateOptions, UseInfiniteQueryOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query'
 import { StackspotAPIError } from '../error/StackspotAPIError'
 
 export interface SessionManager {
@@ -9,58 +9,238 @@ export interface SessionManager {
   getSession(): Session,
 }
 
-export interface RequestOptions {
-  params?: Record<string, string | undefined>,
-  headers?: Record<string, string>,
-}
-
-export interface RequestWithBody extends RequestOptions {
-  body?: string | object | FormData,
-}
-
 export type Env = 'dev' | 'stg' | 'prd'
 
 export type HTTPMethod = 'post' | 'patch' | 'delete' | 'put' | 'get'
 
 export interface OperationConfig<Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result> {
+  /**
+   * The operation name. To be used as key in React Query.
+   */
   name: string,
+  /**
+   * The function to run once the operation is called.
+   * @param abortSignal the AbortSignal to pass to any request made.
+   * @param variables if this operation accepts variables, the second parameter is the variables object.
+   * @returns the operation result (this should not be a Response object, but it could be its body).
+   */
   request: (...args: Args) => Promise<Result>,
+  /**
+   * The function to run once one asks if the operation is allowed.
+   * @param variables if this operation accepts variables, the single parameter is the variables object.
+   * @returns a promise that resolves to true if the operation is allowed and false otherwise.
+   */
   permission: (...args: Args extends [AbortSignal] ? [] : [Args[1]]) => Promise<boolean>,
 }
 
+
+export interface InfiniteQueryOptions<Variables, Result, PageParamName extends keyof Variables, Accumulator extends keyof Result | ''> {
+  /**
+   * The name of the variable that controls the current page.
+   */
+  pageParamName: PageParamName,
+  /**
+   * The name of the property in the Result that contains the items of a page. If the result itself is the array of items, use an empty
+   * string ('').
+   */
+  accumulator?: Accumulator,
+  /**
+   * The initial value for page variable.
+   */
+  initialPageParam: Variables[PageParamName],
+  /**
+   * Some defaults to be used when a variable is not specified.
+   */
+  defaultVariables?: Partial<Variables>,
+  /**
+   * A function that determines the value of the page variable in order to get the next page.
+   * @parar context the current context with the variables and page details.
+   * @returns undefined or null if there are no more pages. The next value for the page variable otherwise.
+   */
+  getNextPageParam: (context: {
+    /**
+     * the original set of variables passed to the hook `useInfiniteQuery`.
+     */
+    variables: Variables,
+    /**
+     * the last page Result.
+     */
+    lastPage: Result,
+    /**
+     * the Results of each page.
+     */
+    allPages: Result[],
+    /**
+     * the value of the page variable used to retrieve the last page.
+     */
+    lastPageParam: Variables[PageParamName],
+    /**
+     * the values of the page variable for requesting each of the pages.
+     */
+    allPageParams:  Variables[PageParamName][],
+  }) => Variables[PageParamName] | undefined | null,
+}
+
 export interface FullOperationConfig<
   Args extends [AbortSignal, Record<string, any>] | [AbortSignal], Result
 > extends OperationConfig<Args, Result>  {
+  /**
+   * The name of the API where this operation is called: used for composing a query key.
+   */
   apiName: string,
 }
 
+export type InfiniteQueryConfig<
+  Variables extends Record<string, any>,
+  Result,
+  PageParamName extends keyof Variables,
+  Accumulator extends keyof Result | '',
+> = OperationConfig<[AbortSignal, Variables], Result> & InfiniteQueryOptions<Variables, Result, PageParamName, Accumulator>
+
 export interface OperationObject<Variables> {
+  /**
+   * Checks if this operation is allowed for the user currently logged in.
+   * @param variables the variables for the operation, if a required url parameter is not provided, it's replaced by a default string.
+   * @returns a promise that resolves to true if the operation is allowed or false otherwise.
+   * @throws `StackspotAPIError`
+   */
   isAllowed: (...args: Variables extends void ? [] : [variables?: Partial<Variables>]) => Promise<boolean>,
+  /**
+   * Same as `isAllowed`, but a React Hook instead.
+   * @param args if this operation accepts variables, the first argument should be the variables and the second the query options
+   * (optional). If it doesn't accept variables, the single optional argument must be the query options. Moreover, if a required url
+   * parameter is not provided, it's replaced by a default string.
+   * @returns an array with 4 items:
+   * - [0]: true if allowed, false if not allowed, undefined if not fetched.
+   * - [1]: true if pending, false otherwise.
+   * - [2]: a StackspotAPIError if an error happens, null or undefined otherwise.
+   * - [3]: the original UseQueryResult object, from ReactQuery.
+   */
   useAllowed: (
     ...args: Variables extends void
       ? [options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
       : [variables?: Partial<Variables>, options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
   ) => Readonly<[boolean | undefined, boolean, StackspotAPIError | null | undefined, UseQueryResult<boolean, StackspotAPIError>]>,
+  /**
+   * Gets the key for the query used to verify if this operation is allowed.
+   * 
+   * Attention: invalidating this key won't clear the cache, since the `@stack-spot/opa` library doesn't support individual cache
+   * invalidation.
+   * @param args if this operation accepts variables, the first argument should be the variables and the second the query options
+   * (optional). If it doesn't accept variables, the single optional argument must be the query options. Moreover, if a required url
+   * parameter is not provided, it's replaced by a default string.
+   * @returns the query key.
+   */
   getPermissionKey: (...args: Variables extends void ? [] : [variables?: Partial<Variables>]) => any[],
+  /**
+   * Cancels the request if it hasn't finished yet.
+   * 
+   * A canceled request will fail by throwing a `CanceledError`.
+   * 
+   * @param variables the variables for the operation. If not provided, this will cancel all requests in progress for this operation.
+   * @returns true if any request has been canceled, false otherwise.
+   */
   cancel: (variables?: Partial<Variables>) => boolean,
 }
 
 export interface QueryObject<Variables, Result> extends OperationObject<Variables> {
+  /**
+   * Runs the query operation.
+   * @param variables the request variables if this query accepts variables. 
+   * @returns a Promise with the response data
+   * @throws `StackspotAPIError`
+   */
   query: (...args: Variables extends void ? [] : [variables: Variables]) => Promise<Result>,
+  /**
+   * Same as `query`, but, instead of an async function, this is a React Hook that expects a React Suspense environment.
+   * 
+   * If you want a hook that performs a stateful query instead of relying in Suspense, call `useStatefulQuery` instead.
+   * 
+   * @param args if this query accepts variables, the first argument should be the variables and the second the query options
+   * (optional). If it doesn't accept variables, the single optional argument must be the query options.
+   * @returns the response data or undefined if not fetched.
+   * @throws `StackspotAPIError`
+   * @throws `Promise<Result>`
+   */
   useQuery: (
     ...args: Variables extends void
       ? [options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
       : [variables: Variables, options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
   ) => Result | undefined,
+  /**
+   * Same as `query`, but a React Hook instead.
+   * @param args if this query accepts variables, the first argument should be the variables and the second the query options
+   * (optional). If it doesn't accept variables, the single optional argument must be the query options.
+   * @returns an array with 4 items:
+   * - [0]: the response data or undefined if not fetched.
+   * - [1]: true if pending, false otherwise.
+   * - [2]: a StackspotAPIError if an error happens, null or undefined otherwise.
+   * - [3]: the original UseQueryResult object, from ReactQuery.
+   */
   useStatefulQuery: (
     ...args: Variables extends void
       ? [options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
       : [variables: Variables, options?: Omit<UseQueryOptions, 'queryFn' | 'queryKey'>]
   ) => Readonly<[Result | undefined, boolean, StackspotAPIError | null | undefined, UseQueryResult<Result, StackspotAPIError>]>,
+  /**
+   * Invalidates the cache for this query. A specific query can be invalidated by passing an argument (variables).
+   * @param variables if this query accepts variables, a query with specific variables can be invalidated.
+   * @returns a promise that resolves once the cache is invalidated.
+   */
   invalidate: (...args: Variables extends void ? [] : [variables?: Partial<Variables>]) => Promise<void>,
+  /**
+   * Gets the key for this query.
+   * @param variables the variables for the query. 
+   * @returns the query key.
+   */
   getKey: (...args: Variables extends void ? [] : [variables?: Partial<Variables>]) => any[],
 }
 
+export type UseInfiniteQueryObjectOptions = Omit<UseInfiniteQueryOptions, 'queryFn' | 'queryKey' | 'getNextPageParam' | 'initialPageParam'>
+
+export interface InfiniteQueryObject<Variables, Result, Accumulator extends keyof Result | ''> extends QueryObject<Variables, Result> {
+  /**
+   * Builds up a list with the result of multiple pages. This relies on React Suspense for error and first-loading feedbacks.
+   * 
+   * Equivalent to React Query's `useSuspenseInfiniteQuery`.
+   * @param variables the variables for the query.
+   * @param options the options for the query.
+   * @returns an array with 2 items:
+   * - [0]: the list of items.
+   * - [1]: the original UseInfiniteQueryResult object, from ReactQuery.
+   */
+  useInfiniteQuery: (
+    ...args: Partial<Variables> extends Variables
+      ? [variables?: Variables, options?: UseInfiniteQueryObjectOptions]
+      : [variables: Variables, options?: UseInfiniteQueryObjectOptions]
+  ) => Readonly<[
+    (Accumulator extends keyof Result ? Result[Accumulator] : Result) | undefined,
+    UseInfiniteQueryResult<InfiniteData<Result>, StackspotAPIError>,
+  ]>,
+  /**
+   * Builds up a list with the result of multiple pages.
+   * 
+   * Equivalent to React Query's `useInfiniteQuery`.
+   * @param variables the variables for the query.
+   * @param options the options for the query.
+   * @returns an array with 4 items:
+   * - [0]: the list of items.
+   * - [1]: true if fetching the first page, false otherwise.
+   * - [2]: a StackspotAPIError if an error happens, null or undefined otherwise.
+   * - [3]: the original UseInfiniteQueryResult object, from ReactQuery.
+   */
+  useStatefulInfiniteQuery: (
+    ...args: Partial<Variables> extends Variables
+      ? [variables?: Variables, options?: Omit<UseInfiniteQueryOptions, 'queryFn' | 'queryKey' | 'getNextPageParam' | 'initialPageParam'>]
+      : [variables: Variables, options?: Omit<UseInfiniteQueryOptions, 'queryFn' | 'queryKey' | 'getNextPageParam' | 'initialPageParam'>]
+  ) => Readonly<[
+    (Accumulator extends keyof Result ? Result[Accumulator] : Result) | undefined,
+    boolean,
+    StackspotAPIError | undefined | null,
+    UseInfiniteQueryResult<InfiniteData<Result>, StackspotAPIError>,
+  ]>,
+}
+
 export interface AutoQueryObjectParams<Variables, Result> {
   apiName: string,
   fn: ((variables: Variables, opts?: RequestOpts) => Promise<Result>) | ((opts?: RequestOpts) => Promise<Result>),
@@ -69,14 +249,30 @@ export interface AutoQueryObjectParams<Variables, Result> {
 }
 
 export interface MutationObject<Variables, Result> extends OperationObject<Variables> {
+  /**
+   * Runs the mutation and returns a promise.
+   * @param args the variables for the mutation.
+   * @returns a promise that resolves to the response's data.
+   */
   mutate: (...args: Variables extends void ? [] : [variables: Variables]) => Promise<Result>,
+  /**
+   * A React hook equivalent to React Query's `useMutation`. It creates a mutation function and the mutation states.
+   * @param options the options for `useMutation`
+   * @returns an array with 4 items:
+   * - [0]: the mutation function (equivalent to `mutateAsync` from the result of a `useMutation`).
+   * - [1]: true if pending, false otherwise.
+   * - [2]: a StackspotAPIError if an error happens, undefined otherwise.
+   * - [3]: the original UseMutationResult object, from ReactQuery.
+   * 
+   */
   useMutation: (options?: Omit<UseMutationOptions<Result, StackspotAPIError, Variables>, 'mutationFn'>) =>
     Readonly<[
       (...args: Variables extends void
         ? [options?:  MutateOptions<Result, StackspotAPIError>]
         : [variables: Variables, options?: MutateOptions<Result, StackspotAPIError, Variables>]
       ) => Promise<Result>,
-      boolean, StackspotAPIError | undefined,
+      boolean,
+      StackspotAPIError | undefined,
       UseMutationResult<Result, StackspotAPIError, Variables>,
     ]>,
 }