@stack-spot/portal-network 0.184.0 → 0.185.0-beta.1

package/src/network/types.ts

@@ -1,294 +1,294 @@
-import type { RequestOpts } from '@oazapfts/runtime'
-import { Session } from '@stack-spot/auth'
-import { InfiniteData, MutateOptions, UseInfiniteQueryOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query'
-import { ServerSentEventMessage } from 'fetch-event-stream'
-import { StackspotAPIError } from '../error/StackspotAPIError'
-
-export interface SessionManager {
-  hasSession(): boolean,
-  endSession(): void,
-  getSession(): Session,
-}
-
-export type Tenant = 'stackspot' | 'itau'
-
-export type Env = 'dev' | 'stg' | 'prd'
-
-export type HTTPMethod = 'post' | 'patch' | 'delete' | 'put' | 'get'
-
-export type FetchEventStream = AsyncGenerator<ServerSentEventMessage, void, unknown>
-
-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.
-   * @param 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,
-  transformError: (error: any) => StackspotAPIError,
-}
-
-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[],
-}
-
-export type UseQueryObjectOptions<Result> = Omit<UseQueryOptions<Result, StackspotAPIError>, 'queryFn' | 'queryKey'>
-
-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.
-   * @throws `StackspotAPIError`
-   * @throws `Promise<Result>`
-   */
-  useQuery: (
-    ...args: Variables extends void
-      ? [options?: UseQueryObjectOptions<Result>]
-      : [variables: Variables, options?: UseQueryObjectOptions<Result>]
-  ) => Result,
-  /**
-   * 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?: UseQueryObjectOptions<Result>]
-      : [variables: Variables, options?: UseQueryObjectOptions<Result>]
-  ) => 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[],
-  /**
-   * Cancels the query if it hasn't finished yet.
-   * 
-   * @param variables the variables for the operation. If not provided, this will cancel all requests in progress for this query.
-   */
-  cancel: (variables?: Partial<Variables>) => void,
-}
-
-export type UseInfiniteQueryObjectOptions<Result> = Omit<
-  UseInfiniteQueryOptions<Result, StackspotAPIError>,
-  '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<Result>]
-      : [variables: Variables, options?: UseInfiniteQueryObjectOptions<Result>]
-  ) => Readonly<[
-    (Accumulator extends keyof Result ? Result[Accumulator] : Result),
-    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?: UseInfiniteQueryObjectOptions<Result>]
-      : [variables: Variables, options?: UseInfiniteQueryObjectOptions<Result>]
-  ) => 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>),
-  onFetchPermission: typeof fetch,
-  transformError?: (error: any) => StackspotAPIError,
-}
-
-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 ? [signal?: AbortSignal] : [variables: Variables, signal?: AbortSignal]) => 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'> & { signal?: AbortSignal }) =>
-    Readonly<[
-      (...args: Variables extends void
-        ? [options?:  MutateOptions<Result, StackspotAPIError>]
-        : [variables: Variables, options?: MutateOptions<Result, StackspotAPIError, Variables>]
-      ) => Promise<Result>,
-      boolean,
-      StackspotAPIError | undefined,
-      UseMutationResult<Result, StackspotAPIError, Variables>,
-    ]>,
-}
-
-export type OperationVariables<T extends Pick<OperationObject<any>, 'isAllowed'>> = T extends Pick<OperationObject<infer R>, 'isAllowed'>
-  ? R
-  : never
-export type OperationResult<T extends { query: (variables?: any) => Promise<any> } | { mutate: (variables?: any) => Promise<any> }> = 
-  T extends { query: (variables?: any) => Promise<infer R> } ? R : (
-    T extends { mutate: (variables?: any) => Promise<infer R> } ? R : never
-  )
+import type { RequestOpts } from '@oazapfts/runtime'
+import { Session } from '@stack-spot/auth'
+import { InfiniteData, MutateOptions, UseInfiniteQueryOptions, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query'
+import { ServerSentEventMessage } from 'fetch-event-stream'
+import { StackspotAPIError } from '../error/StackspotAPIError'
+
+export interface SessionManager {
+  hasSession(): boolean,
+  endSession(): void,
+  getSession(): Session,
+}
+
+export type Tenant = 'stackspot' | 'itau'
+
+export type Env = 'dev' | 'stg' | 'prd'
+
+export type HTTPMethod = 'post' | 'patch' | 'delete' | 'put' | 'get'
+
+export type FetchEventStream = AsyncGenerator<ServerSentEventMessage, void, unknown>
+
+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.
+   * @param 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,
+  transformError: (error: any) => StackspotAPIError,
+}
+
+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[],
+}
+
+export type UseQueryObjectOptions<Result> = Omit<UseQueryOptions<Result, StackspotAPIError>, 'queryFn' | 'queryKey'>
+
+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.
+   * @throws `StackspotAPIError`
+   * @throws `Promise<Result>`
+   */
+  useQuery: (
+    ...args: Variables extends void
+      ? [options?: UseQueryObjectOptions<Result>]
+      : [variables: Variables, options?: UseQueryObjectOptions<Result>]
+  ) => Result,
+  /**
+   * 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?: UseQueryObjectOptions<Result>]
+      : [variables: Variables, options?: UseQueryObjectOptions<Result>]
+  ) => 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[],
+  /**
+   * Cancels the query if it hasn't finished yet.
+   * 
+   * @param variables the variables for the operation. If not provided, this will cancel all requests in progress for this query.
+   */
+  cancel: (variables?: Partial<Variables>) => void,
+}
+
+export type UseInfiniteQueryObjectOptions<Result> = Omit<
+  UseInfiniteQueryOptions<Result, StackspotAPIError>,
+  '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<Result>]
+      : [variables: Variables, options?: UseInfiniteQueryObjectOptions<Result>]
+  ) => Readonly<[
+    (Accumulator extends keyof Result ? Result[Accumulator] : Result),
+    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?: UseInfiniteQueryObjectOptions<Result>]
+      : [variables: Variables, options?: UseInfiniteQueryObjectOptions<Result>]
+  ) => 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>),
+  onFetchPermission: typeof fetch,
+  transformError?: (error: any) => StackspotAPIError,
+}
+
+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 ? [signal?: AbortSignal] : [variables: Variables, signal?: AbortSignal]) => 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'> & { signal?: AbortSignal }) =>
+    Readonly<[
+      (...args: Variables extends void
+        ? [options?:  MutateOptions<Result, StackspotAPIError>]
+        : [variables: Variables, options?: MutateOptions<Result, StackspotAPIError, Variables>]
+      ) => Promise<Result>,
+      boolean,
+      StackspotAPIError | undefined,
+      UseMutationResult<Result, StackspotAPIError, Variables>,
+    ]>,
+}
+
+export type OperationVariables<T extends Pick<OperationObject<any>, 'isAllowed'>> = T extends Pick<OperationObject<infer R>, 'isAllowed'>
+  ? R
+  : never
+export type OperationResult<T extends { query: (variables?: any) => Promise<any> } | { mutate: (variables?: any) => Promise<any> }> = 
+  T extends { query: (variables?: any) => Promise<infer R> } ? R : (
+    T extends { mutate: (variables?: any) => Promise<infer R> } ? R : never
+  )

package/src/types.ts

@@ -1 +1 @@
-export type StreamingStatus = 'pending' | 'success' | 'error'
+export type StreamingStatus = 'pending' | 'success' | 'error'