@stack-spot/portal-network 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.2.0](https://github.com/stack-spot/portal-commons/compare/portal-network-v0.1.0...portal-network@v0.2.0) (2024-07-31)
+
+
+### Features
+
+* network library ([eec8b1b](https://github.com/stack-spot/portal-commons/commit/eec8b1b24c77d055884b8ed8c2ccac452c5b16e2))
+* network: infinite query ([#214](https://github.com/stack-spot/portal-commons/issues/214)) ([aded3f7](https://github.com/stack-spot/portal-commons/commit/aded3f78665a829fd31d78766be7d5942aaa62e3))

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@stack-spot/portal-network",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
+    "./package.json": "./package.json",
     "./api/*": "./dist/api/*.js"
   },
+  "scripts": {
+    "build": "rimraf dist && tsc-silent -p tsconfig.build.json --suppress @/src/api/ && tsc-esm-fix --target='dist'",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "generate": "tsx ./scripts/generate-apis.ts"
+  },
   "peerDependencies": {
     "@stack-spot/auth": "^5.2.0",
     "@stack-spot/opa": "^2.2.0",
@@ -47,10 +53,5 @@
   "dependencies": {
     "@oazapfts/runtime": "^1.0.3",
     "lodash": "^4.17.21"
-  },
-  "scripts": {
-    "build": "rimraf dist && tsc-silent -p tsconfig.build.json --suppress @/src/api/ && tsc-esm-fix --target='dist'",
-    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
-    "generate": "tsx ./scripts/generate-apis.ts"
   }
 }

package/src/apis.json

@@ -1,8 +1,8 @@
 {
   "ai": {
     "url": {
-      "dev": "https://code-buddy-api.dev.stackspot.com",
-      "stg": "https://code-buddy-api.stg.stackspot.com",
+      "dev": "https://genai-code-buddy-api.dev.stackspot.com",
+      "stg": "https://genai-code-buddy-api.stg.stackspot.com",
       "prd": "https://genai-code-buddy-api.stackspot.com"
     },
     "docs": "/openapi.json"
@@ -79,14 +79,6 @@
     },
     "docs": "/v3/api-docs"
   },
-  "plugin": {
-    "url": {
-      "dev": "https://content-plugin-api.dev.stackspot.com",
-      "stg": "https://content-plugin-api.stg.stackspot.com",
-      "prd": "https://plugin-api.v1.stackspot.com"
-    },
-    "docs": "/openapi.json"
-  },
   "workflows": {
     "url": {
       "dev": "https://workflow-workflow-api.dev.stackspot.com",

package/src/client/account.ts

@@ -2,7 +2,8 @@ import { HttpError } from '@oazapfts/runtime'
 import {
   accountDataIsAvailable, create, createPartner,
   defaults,
-  deletePartner, getFeatures, getPartnerAccount, getPartnersSharingAllowed,
+  deletePartner, getAccountMembers1, getFeatures,
+  getPartnerAccount, getPartnersSharingAllowed,
   getPersonalClientCredentials, updatePartnerAccountAdminData, updatePartnerAccountData, validateNewPartnerData,
   validatePartnerAssociationLimit,
 } from '../api/account'
@@ -21,17 +22,54 @@ class AccountClient extends ReactQueryNetworkClient {
     return new DefaultAPIError(error.data, error.status, accountDictionary, error.headers)
   }
 
+  /**
+   * Get credentials from personal service client (create if not exists one to the logged user).
+   */
   generatePersonalClientCredentials = this.mutation(getPersonalClientCredentials)
-  create = this.mutation(create)
+  /**
+   * Create a Feature Flag
+   */
+  createFeatureFlag = this.mutation(create)
+  /**
+   * Returns information if account data (name and slug) are available to be registered
+   */
   isAvailable = this.query(accountDataIsAvailable)
+  /**
+   * List Feature Flags in an Account
+   */
   featureFlags = this.query(getFeatures)
+  /**
+   * Get Partners with whom it is allowed to share content.
+   */
   partners = this.query(getPartnersSharingAllowed)
+  /**
+   * Get Partner by account Id
+   */
   partner = this.query(getPartnerAccount)
+  /**
+   * Create an Account Order for Partner
+   */
   createPartner = this.mutation(createPartner)
+  /**
+   * Update Partner Account data.
+   */
   updatePartner = this.mutation(updatePartnerAccountData)
+  /**
+   * Update Partner Account Admin data.
+   */
   updatePartnerAdmin = this.mutation(updatePartnerAccountAdminData)
+  /**
+   * Delete Partner
+   */
   deactivatePartner = this.mutation(deletePartner)
+  /**
+   * Validate new Partner account data
+   */
   validateNewPartnerData = this.mutation(validateNewPartnerData)
+  /**
+   * Validates the association limit for the partner. Yields `{ isValid: true }` if valid or `{ isValid: false, message: string }`
+   * otherwise.
+   */
   validatePartnerAssociationLimit = this.query({
     name: 'validatePartnerAssociationLimit',
     request: async (signal) => {
@@ -47,6 +85,10 @@ class AccountClient extends ReactQueryNetworkClient {
       }
     },
   })
+  /**
+   * Get all members (paginated).
+   */
+  allMembers = this.infiniteQuery(getAccountMembers1)
 }
 
 export const accountClient = new AccountClient()

package/src/error/CanceledError.ts

@@ -1,5 +1,8 @@
 import { StackspotAPIError } from './StackspotAPIError'
 
+/**
+ * This error is thrown when a request is canceled by the user before it completes.
+ */
 export class CanceledError extends StackspotAPIError {
   constructor() {
     super({ status: 0, message: lang => lang === 'en' ? 'Canceled by the user' : 'Cancelado pelo usuário' })

package/src/error/DefaultAPIError.ts

@@ -34,11 +34,37 @@ function createMessage(raw: ErrorResponse, dictionary: Dictionary, language: Lan
   return `${title}\n${details?.join('\n')}`
 }
 
+/**
+ * This represents the Error thrown by most Stackspot APIs.
+ */
 export class DefaultAPIError extends StackspotAPIError {
+  /**
+   * The error object as defined by the Stackspot API. If the response doesn't match the expected format this will be undefined.
+   */
   data?: ErrorResponse
+  /**
+   * The response data, if this matches the expected format expected by a Stackspot Error, it will be the same as `data`.
+   */
   raw?: any
 
-  constructor(rawResponse: any, status: number, dictionary: Dictionary, headers?: Headers) {
+  constructor(
+    /**
+     * The response's data
+     */
+    rawResponse: any,
+    /**
+     * The response's status
+     */
+    status: number,
+    /**
+     * A dictionary for translating error codes and descriptions.
+     */
+    dictionary: Dictionary,
+    /**
+     * The response's headers.
+     */
+    headers?: Headers,
+  ) {
     super({
       status: status,
       code: rawResponse.code,

package/src/error/StackspotAPIError.ts

@@ -3,16 +3,42 @@ import { Language, getLanguage } from '@stack-spot/portal-translate'
 type InternationalizedMessage = (language: Language) => string
 
 interface ErrorProperties {
+  /**
+   * The response's status.
+   */
   status: number,
+  /**
+   * The response's headers.
+   */
   headers?: Headers,
+  /**
+   * The error code defined by the API, if any.
+   */
   code?: string,
+  /**
+   * The error message: may be a simple string or a function that returns a string depending on the language passed as parameter.
+   * 
+   * If not provided, will attempt to use the error code or 'unknown'.
+   */
   message?: InternationalizedMessage | string,
+  /**
+   * The error's stack trace, if any.
+   */
   stack?: string,
 }
 
 export class StackspotAPIError extends Error {
+  /**
+   * The response's status.
+   */
   status: number
+  /**
+   * The response's headers.
+   */
   headers: Headers | undefined
+  /**
+   * The error code defined by the API, if any.
+   */
   code: string | undefined
   private intl?: InternationalizedMessage
 
@@ -25,7 +51,13 @@ export class StackspotAPIError extends Error {
     this.intl = typeof message === 'string' ? () => message : message
   }
 
+  /**
+   * Translates the error to the given language.
+   * @param language 
+   * @returns an error message
+   */
   translate(language: Language = getLanguage()) {
-    return this.intl?.(language) ?? this.message
+    const unknown = language === 'en' ? 'unknown error' : 'erro desconhecido'
+    return this.intl?.(language) ?? this.message ?? this.code ?? this.status === 0 ? unknown : `${this.status}`
   }
 }

package/src/network/AutoInfiniteQuery.ts

@@ -0,0 +1,97 @@
+/* eslint-disable react-hooks/rules-of-hooks */
+
+import {
+  InfiniteData, QueryFunctionContext, QueryKey,
+  UseInfiniteQueryResult,
+  useInfiniteQuery,
+  useSuspenseInfiniteQuery,
+} from '@tanstack/react-query'
+import { StackspotAPIError } from '../error/StackspotAPIError'
+import { AutoQuery } from './AutoQuery'
+import { queryClient } from './react-query-client'
+import { AutoQueryObjectParams, InfiniteQueryObject, InfiniteQueryOptions, UseInfiniteQueryObjectOptions } from './types'
+
+export class AutoInfiniteQuery<Variables, Result, PageParamName extends keyof Variables, Accumulator extends keyof Result | ''>
+  extends AutoQuery<Variables, Result>
+  implements InfiniteQueryObject<Variables, Result, Accumulator>
+{
+  private options: Required<InfiniteQueryOptions<Variables, Result, PageParamName, Accumulator | ''>>
+
+  constructor(
+    params: AutoQueryObjectParams<Variables, Result>,
+    options: InfiniteQueryOptions<Variables, Result, PageParamName, Accumulator>,
+  ) {
+    super(params)
+    this.options = {
+      ...options,
+      accumulator: options.accumulator ?? '',
+      defaultVariables: options.defaultVariables ?? {},
+    }
+  }
+
+  private createInfiniteQueryFn(
+    variables: Variables | undefined,
+  ): (context: QueryFunctionContext<QueryKey, Variables[PageParamName]>) => Promise<Result> {
+    return async ({ pageParam }) => {
+      const paginatedVariables = {
+        ...variables,
+        [this.options.pageParamName]: pageParam ?? variables?.[this.options.pageParamName],
+      } as Variables
+      if (!this.currentRequests.has(paginatedVariables)) this.currentRequests.set(paginatedVariables, this.callFn(paginatedVariables))
+      const result = await this.currentRequests.get(paginatedVariables)
+      this.currentRequests.delete(paginatedVariables)
+      return result!
+    }
+  }
+
+  private getListFromData(data: InfiniteData<Result> | undefined) {
+    return data?.pages.map(
+      page => this.options.accumulator ? page[this.options.accumulator as keyof Result] : page,
+    ).flat() as Accumulator extends keyof Result ? Result[Accumulator] : Result
+  }
+
+  private useInfiniteQueryResult(suspense: boolean, variables = {} as Variables, options?: UseInfiniteQueryObjectOptions) {
+    variables = { ...variables, ...this.options.defaultVariables }
+    const use = suspense ? useSuspenseInfiniteQuery : useInfiniteQuery
+    return use<any, any, any, any, any>({
+      ...options,
+      queryKey: ['infinite', ...this.getKey(variables)],
+      queryFn: this.createInfiniteQueryFn(variables),
+      initialPageParam: this.options.initialPageParam,
+      getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) =>
+        this.options.getNextPageParam({ variables, lastPage, allPages, lastPageParam, allPageParams }),
+    }, queryClient) as UseInfiniteQueryResult<InfiniteData<Result>, StackspotAPIError>
+  }
+
+  useInfiniteQuery(
+    variables?: Variables,
+    options?: UseInfiniteQueryObjectOptions,
+  ): [
+    Accumulator extends keyof Result ? Result[Accumulator] : Result,
+    UseInfiniteQueryResult<InfiniteData<Result>, StackspotAPIError>,
+  ] {
+    const result = this.useInfiniteQueryResult(true, variables, options)
+    return [
+      this.getListFromData(result.data),
+      result,
+    ]
+  }
+
+  useStatefulInfiniteQuery(
+    variables?: Variables,
+    options?: UseInfiniteQueryObjectOptions,
+  ): [
+    Accumulator extends keyof Result ? Result[Accumulator] : Result,
+    boolean,
+    StackspotAPIError | undefined | null,
+    UseInfiniteQueryResult<InfiniteData<Result>, StackspotAPIError>,
+  ] {
+    const result = this.useInfiniteQueryResult(false, variables, options)
+    return [
+      this.getListFromData(result.data),
+      result.isPending,
+      result.error,
+      result,
+    ]
+  }
+}

package/src/network/AutoQuery.ts

@@ -10,7 +10,8 @@ export class AutoQuery<Variables, Result> extends AutoOperation<Variables> imple
   /**
    * Prevents the same request from being triggered more than once if subsequent calls are made before the first ends.
    */
-  private currentRequests = new Map<Variables | undefined, Promise<Result>>()
+  protected currentRequests = new Map<Variables | undefined, Promise<Result>>()
+  
   constructor(params: AutoQueryObjectParams<Variables, Result>) {
     super(params)
   }

package/src/network/ManualInfiniteQuery.ts

@@ -0,0 +1,88 @@
+/* eslint-disable react-hooks/rules-of-hooks */
+
+import { InfiniteData, QueryFunctionContext, QueryKey, UseInfiniteQueryResult, useInfiniteQuery, useSuspenseInfiniteQuery } from '@tanstack/react-query'
+import { StackspotAPIError } from '../error/StackspotAPIError'
+import { ManualQuery } from './ManualQuery'
+import { queryClient } from './react-query-client'
+import { FullOperationConfig, InfiniteQueryConfig, InfiniteQueryObject, UseInfiniteQueryObjectOptions } from './types'
+
+export class ManualInfiniteQuery<
+  Variables extends Record<string, any>,
+  Result,
+  PageParamName extends keyof Variables,
+  Accumulator extends keyof Result | ''
+> extends ManualQuery<Variables, Result> implements InfiniteQueryObject<Variables, Result, Accumulator> {
+  constructor(config: InfiniteQueryConfig<Variables, Result, PageParamName, Accumulator> & { apiName: string }) {
+    super(config as FullOperationConfig<any, any>)
+  }
+
+  private getConfig() {
+    return this.config as unknown as InfiniteQueryConfig<Variables, Result, PageParamName, Accumulator>
+  }
+
+  private createInfiniteQueryFn(
+    variables: Variables,
+  ): (context: QueryFunctionContext<QueryKey, Variables[PageParamName]>) => Promise<Result> {
+    return async ({ pageParam }) => {
+      const paginatedVariables = {
+        ...variables,
+        [this.getConfig().pageParamName]: pageParam ?? variables?.[this.getConfig().pageParamName],
+      } as Variables
+      if (!this.currentRequests.has(paginatedVariables)) this.currentRequests.set(paginatedVariables, this.makeRequest(paginatedVariables))
+      const result = await this.currentRequests.get(paginatedVariables)
+      this.currentRequests.delete(paginatedVariables)
+      return result!
+    }
+  }
+
+  private getListFromData(data: InfiniteData<Result> | undefined) {
+    return data?.pages.map(
+      page => this.getConfig().accumulator ? page[this.getConfig().accumulator as keyof Result] : page,
+    ).flat() as Accumulator extends keyof Result ? Result[Accumulator] : Result
+  }
+
+  private useInfiniteQueryResult(suspense: boolean, variables = {} as Variables, options?: UseInfiniteQueryObjectOptions) {
+    variables = { ...variables, ...this.getConfig().defaultVariables }
+    const use = suspense ? useSuspenseInfiniteQuery : useInfiniteQuery
+    return use<any, any, any, any, any>({
+      ...options,
+      queryKey: ['infinite', ...this.getKey(variables)],
+      queryFn: this.createInfiniteQueryFn(variables),
+      initialPageParam: this.getConfig().initialPageParam,
+      getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) => 
+        this.getConfig().getNextPageParam({ variables, lastPage, allPages, lastPageParam, allPageParams }),
+    }, queryClient) as UseInfiniteQueryResult<InfiniteData<Result>, StackspotAPIError>
+  }
+
+  useInfiniteQuery(
+    variables?: Variables,
+    options?: UseInfiniteQueryObjectOptions,
+  ): [
+    Accumulator extends keyof Result ? Result[Accumulator] : Result,
+    UseInfiniteQueryResult<InfiniteData<Result>, StackspotAPIError>,
+  ] {
+    const result = this.useInfiniteQueryResult(true, variables, options)
+    return [
+      this.getListFromData(result.data),
+      result,
+    ]
+  }
+
+  useStatefulInfiniteQuery(
+    variables?: Variables,
+    options?: UseInfiniteQueryObjectOptions,
+  ): [
+    Accumulator extends keyof Result ? Result[Accumulator] : Result,
+    boolean,
+    StackspotAPIError | undefined | null,
+    UseInfiniteQueryResult<InfiniteData<Result>, StackspotAPIError>,
+  ] {
+    const result = this.useInfiniteQueryResult(false, variables, options)
+    return [
+      this.getListFromData(result.data),
+      result.isPending,
+      result.error,
+      result,
+    ]
+  }
+}

package/src/network/ManualQuery.ts

@@ -13,13 +13,13 @@ export class ManualQuery<
   /**
    * Prevents the same request from being triggered more than once if subsequent calls are made before the first ends.
    */
-  private currentRequests = new Map<Record<string, any> | undefined, Promise<Result>>()
+  protected currentRequests = new Map<Record<string, any> | undefined, Promise<Result>>()
 
   constructor(config: FullOperationConfig<Variables extends void ? [AbortSignal] : [AbortSignal, Variables], Result>) {
     super(config)
   }
 
-  private async makeRequest(variables: Record<string, any> | undefined) {
+  protected async makeRequest(variables: Record<string, any> | undefined) {
     const abortController = new AbortController()
     this.abortMap.set(variables, [abortController])
     try {

package/src/network/NetworkClient.ts

@@ -3,15 +3,35 @@ import { AuthenticationError } from '@stack-spot/auth'
 import { requestPermission } from '@stack-spot/opa'
 import { Env, HTTPMethod, RequestOptions, RequestWithBody, 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 +41,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 +55,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)
   }
@@ -57,8 +89,8 @@ export class NetworkClient {
       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 })
+          ? sessionManager.getSession().fetch(url, { method: method.toUpperCase(), headers, body, signal: request?.signal })
+          : fetch(url, { method: method.toUpperCase(), headers, body, signal: request?.signal })
       )
     } catch (error) {
       if (error instanceof AuthenticationError) sessionManager.endSession()
@@ -66,26 +98,60 @@ export class NetworkClient {
     }
   }
 
-  protected get<T>(path: string, request?: RequestOptions): Promise<T> {
-    return this.sendRequest(path, 'get', request) as Promise<T>
+  /**
+   * Performs a GET request with the parameters provided.
+   * @param path the path to the resource.
+   * @param request the request options.
+   * @returns a promise that resolves to response's data.
+   */
+  protected get(path: string, request?: RequestOptions) {
+    return this.sendRequest(path, 'get', request)
   }
 
-  protected post<T>(path: string, request?: RequestWithBody): Promise<T> {
-    return this.sendRequest(path, 'post', request) as Promise<T>
+  /**
+   * Performs a POST request with the parameters provided.
+   * @param path the path to the resource.
+   * @param request the request options.
+   * @returns a promise that resolves to response's data.
+   */
+  protected post(path: string, request?: RequestWithBody) {
+    return this.sendRequest(path, 'post', request)
   }
 
-  protected put<T>(path: string, request?: RequestWithBody): Promise<T> {
-    return this.sendRequest(path, 'put', request) as Promise<T>
+  /**
+   * Performs a PUT request with the parameters provided.
+   * @param path the path to the resource.
+   * @param request the request options.
+   * @returns a promise that resolves to response's data.
+   */
+  protected put(path: string, request?: RequestWithBody) {
+    return this.sendRequest(path, 'put', request)
   }
 
-  protected patch<T>(path: string, request?: RequestWithBody): Promise<T> {
-    return this.sendRequest(path, 'patch', request) as Promise<T>
+  /**
+   * Performs a PATCH request with the parameters provided.
+   * @param path the path to the resource.
+   * @param request the request options.
+   * @returns a promise that resolves to response's data.
+   */
+  protected patch(path: string, request?: RequestWithBody) {
+    return this.sendRequest(path, 'patch', request)
   }
 
-  protected delete<T>(path: string, request?: RequestWithBody): Promise<T> {
-    return this.sendRequest(path, 'delete', request) as Promise<T>
+  /**
+   * Performs a DELETE request with the parameters provided.
+   * @param path the path to the resource.
+   * @param request the request options.
+   * @returns a promise that resolves to response's data.
+   */
+  protected delete(path: string, request?: RequestWithBody) {
+    return this.sendRequest(path, 'delete', request)
   }
 
+  /**
+   * 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