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

package/src/network/NetworkClient.ts

@@ -1,167 +1,167 @@
-import { AuthenticationError, SessionExpiredError } from '@stack-spot/auth'
-import { requestPermission } from '@stack-spot/opa'
-import { events } from 'fetch-event-stream'
-import { getBaseUrlByTenantWithOverride } from '../api-addresses'
-import { StackspotAPIError } from '../error/StackspotAPIError'
-import { Env, FetchEventStream, HTTPMethod, SessionManager, Tenant } from './types'
-
-/**
- * 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>
-  static readonly sessionManager?: SessionManager
-  private static env?: Env
-  private static tenant?: Tenant 
-
-  /**
-   * @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.
-   * @param tenant - {@link Tenant} tenant identifier used to scope requests.
-   */
-  static setup(sessionManager: SessionManager, env: Env, tenant?: Tenant) {
-    //@ts-ignore This is the only place we would link session manager to be set.
-    NetworkClient.sessionManager = sessionManager
-    NetworkClient.env = env
-    NetworkClient.tenant = tenant
-  }
-
-  /**
-   * Retrieves the current environment configuration.
-   *
-   * This method returns the environment setting for the `NetworkClient`.
-   * If no environment is explicitly set, it defaults to `'prd'` (production).
-   *
-   * @returns {Env} The current environment configuration, either the value of `NetworkClient.env` or `'prd'` if not set.
-   */
-  static getEnv(): Env {
-    return NetworkClient.env || 'prd'
-  }
-
-  private uninitializedError() {
-    return new Error('Please, call "NetworkClient.setup(sessionManager, env)" before attempting to make a request.')
-  }
-  
-  /**
-   * Resolves the final base URL for the current environment.
-   * If a local API override exists for the current environment and current resource (api name), it will be use instead.
-   * @returns the final baseURL for the current environment, considering overrides if available.
-   */
-  protected getBaseURL(): string {
-    return getBaseUrlByTenantWithOverride(this.baseURL, NetworkClient.env, NetworkClient.tenant);
-  }
-
-  /**
-   * 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.
-    const fixedPath = path.replace(/^\//, '')
-    // the baseUrl must end with "/", otherwise, the last of its part will get replaced by the path, instead of concatenated with.
-    const fixedBaseUrl = this.getBaseURL().replace(/([^/])$/, '$1/')
-    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 async requestPermission(method: HTTPMethod, path: string, body?: string | object): Promise<boolean> {
-    try {
-      return await requestPermission(method, this.resolveURL(path).toString(), body)
-    } catch (error) {
-      if (error instanceof AuthenticationError) {
-        this.getSessionManager().endSession()
-      }
-      return false
-    }
-  }
-
-  private getSessionManager() {
-    const sessionManager = NetworkClient.sessionManager
-    if (!sessionManager) throw this.uninitializedError()
-    return sessionManager
-  }
-
-  /**
-   * 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()
-    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 {
-      return sessionManager.hasSession() ? sessionManager.getSession().fetch(inputWithBaseUrl, init) : fetch(inputWithBaseUrl, init)
-    } catch (error) {
-      if (error instanceof AuthenticationError || error instanceof SessionExpiredError) sessionManager.endSession()
-      throw error
-    }
-  }
-
-  /**
-   * Reads an EventSource from the endpoint. Differently than the original specification, this allows common HTTP requests with method and
-   * body to be made.
-   * 
-   * @example
-   * ```
-   * let events = this.stream('url', options)
-   * for await (let event of events) {
-   *   console.log('<<', event.data)
-   * }
-   * ```
-   * @param input the url or request object.
-   * @param init the fetch options.
-   * @returns a promise with a FetchEventStream, which is an AsyncGenerator.
-   */
-  protected async stream(input: string | URL | Request, init?: RequestInit): Promise<FetchEventStream> {
-    const response = await this.fetch(input, init)
-    if (!response.ok) {
-      let message = `Failed to get stream response. Error status: ${response.status}.`
-      try {
-        message = await response.text()
-      } catch { /* empty */ }
-      throw new StackspotAPIError({ status: response.status, headers: response.headers, message })
-    }
-    return events(response, init?.signal)
-  }
-
-  /**
-   * 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
-  }
-}
+import { AuthenticationError, SessionExpiredError } from '@stack-spot/auth'
+import { requestPermission } from '@stack-spot/opa'
+import { events } from 'fetch-event-stream'
+import { getBaseUrlByTenantWithOverride } from '../api-addresses'
+import { StackspotAPIError } from '../error/StackspotAPIError'
+import { Env, FetchEventStream, HTTPMethod, SessionManager, Tenant } from './types'
+
+/**
+ * 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>
+  static readonly sessionManager?: SessionManager
+  private static env?: Env
+  private static tenant?: Tenant 
+
+  /**
+   * @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.
+   * @param tenant - {@link Tenant} tenant identifier used to scope requests.
+   */
+  static setup(sessionManager: SessionManager, env: Env, tenant?: Tenant) {
+    //@ts-ignore This is the only place we would link session manager to be set.
+    NetworkClient.sessionManager = sessionManager
+    NetworkClient.env = env
+    NetworkClient.tenant = tenant
+  }
+
+  /**
+   * Retrieves the current environment configuration.
+   *
+   * This method returns the environment setting for the `NetworkClient`.
+   * If no environment is explicitly set, it defaults to `'prd'` (production).
+   *
+   * @returns {Env} The current environment configuration, either the value of `NetworkClient.env` or `'prd'` if not set.
+   */
+  static getEnv(): Env {
+    return NetworkClient.env || 'prd'
+  }
+
+  private uninitializedError() {
+    return new Error('Please, call "NetworkClient.setup(sessionManager, env)" before attempting to make a request.')
+  }
+  
+  /**
+   * Resolves the final base URL for the current environment.
+   * If a local API override exists for the current environment and current resource (api name), it will be use instead.
+   * @returns the final baseURL for the current environment, considering overrides if available.
+   */
+  protected getBaseURL(): string {
+    return getBaseUrlByTenantWithOverride(this.baseURL, NetworkClient.env, NetworkClient.tenant);
+  }
+
+  /**
+   * 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.
+    const fixedPath = path.replace(/^\//, '')
+    // the baseUrl must end with "/", otherwise, the last of its part will get replaced by the path, instead of concatenated with.
+    const fixedBaseUrl = this.getBaseURL().replace(/([^/])$/, '$1/')
+    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 async requestPermission(method: HTTPMethod, path: string, body?: string | object): Promise<boolean> {
+    try {
+      return await requestPermission(method, this.resolveURL(path).toString(), body)
+    } catch (error) {
+      if (error instanceof AuthenticationError) {
+        this.getSessionManager().endSession()
+      }
+      return false
+    }
+  }
+
+  private getSessionManager() {
+    const sessionManager = NetworkClient.sessionManager
+    if (!sessionManager) throw this.uninitializedError()
+    return sessionManager
+  }
+
+  /**
+   * 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()
+    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 {
+      return sessionManager.hasSession() ? sessionManager.getSession().fetch(inputWithBaseUrl, init) : fetch(inputWithBaseUrl, init)
+    } catch (error) {
+      if (error instanceof AuthenticationError || error instanceof SessionExpiredError) sessionManager.endSession()
+      throw error
+    }
+  }
+
+  /**
+   * Reads an EventSource from the endpoint. Differently than the original specification, this allows common HTTP requests with method and
+   * body to be made.
+   * 
+   * @example
+   * ```
+   * let events = this.stream('url', options)
+   * for await (let event of events) {
+   *   console.log('<<', event.data)
+   * }
+   * ```
+   * @param input the url or request object.
+   * @param init the fetch options.
+   * @returns a promise with a FetchEventStream, which is an AsyncGenerator.
+   */
+  protected async stream(input: string | URL | Request, init?: RequestInit): Promise<FetchEventStream> {
+    const response = await this.fetch(input, init)
+    if (!response.ok) {
+      let message = `Failed to get stream response. Error status: ${response.status}.`
+      try {
+        message = await response.text()
+      } catch { /* empty */ }
+      throw new StackspotAPIError({ status: response.status, headers: response.headers, message })
+    }
+    return events(response, init?.signal)
+  }
+
+  /**
+   * 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
+  }
+}