@inweb/client/src/Api/IHttpClient.ts

JavaScript REST API client for the Open Cloud Server

///////////////////////////////////////////////////////////////////////////////
// Copyright (C) 2002-2026, Open Design Alliance (the "Alliance").
// All rights reserved.
//
// This software and its documentation and related materials are owned by
// the Alliance. The software may only be incorporated into application
// programs owned by members of the Alliance, subject to a signed
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable
// trade secrets of the Alliance and its suppliers. The software is also
// protected by copyright law and international treaty provisions. Application
// programs incorporating this software must include the following statement
// with their copyright notices:
//
//   This application incorporates Open Design Alliance software pursuant to a
//   license agreement with Open Design Alliance.
//   Open Design Alliance Copyright (C) 2002-2026 by Open Design Alliance.
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////

/**
 * Defines the HTTP client used to send requests to the REST API server.
 */
export interface IHttpClient {
  /**
   * REST API server URL.
   */
  serverUrl: string;

  /**
   * Default HTTP headers for all requests. You can add specific headers at any time.
   *
   * The following headers are added automatically:
   *
   * - `Authorization`- Added after user log in.
   * - `Content-Type` - Added before sending `POST` and `PUT` request according the request body.
   */
  headers: HeadersInit;

  /**
   * Current logged in user ID.
   */
  signInUserId: string;

  /**
   * `True` if the current logged in user is and administrator.
   */
  signInUserIsAdmin: boolean;

  /**
   * Sends the `GET` request to the specified endpoint.
   *
   * @param relativePath - Endpoint relative path.
   * @param init - A set of options that can be used to configure a fetch request. See
   *   {@link https://developer.mozilla.org/docs/Web/API/RequestInit | RequestInit} for more details.
   */
  get(relativePath: string, init?: RequestInit): Promise<Response>;

  /**
   * Sends the `POST` request to the specified endpoint.
   *
   * @param relativePath - Endpoint relative path.
   * @param body - Request body. Can be
   *   {@link https://developer.mozilla.org/docs/Web/API/FormData | FormData},
   *   {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer | ArrayBuffer},
   *   {@link https://developer.mozilla.org/docs/Web/API/Blob/Blob | Blob}, JSON object or plain text.
   * @param init - A set of options that can be used to configure a fetch request. See
   *   {@link https://developer.mozilla.org/docs/Web/API/RequestInit | RequestInit} for more details.
   */
  post(relativePath: string, body?: BodyInit | object, init?: RequestInit): Promise<Response>;

  /**
   * Sends the `PUT` request to the specified endpoint.
   *
   * @param relativePath - Endpoint relative path.
   * @param body - Request body. Can be
   *   {@link https://developer.mozilla.org/docs/Web/API/FormData | FormData},
   *   {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer | ArrayBuffer},
   *   {@link https://developer.mozilla.org/docs/Web/API/Blob/Blob | Blob}, JSON object or plain text.
   * @param init - A set of options that can be used to configure a fetch request. See
   *   {@link https://developer.mozilla.org/docs/Web/API/RequestInit | RequestInit} for more details.
   */
  put(relativePath: string, body?: BodyInit | object, init?: RequestInit): Promise<Response>;

  /**
   * Sends the `DELETE` request to the specified endpoint.
   *
   * @param relativePath - Endpoint relative path.
   * @param init - A set of options that can be used to configure a fetch request. See
   *   {@link https://developer.mozilla.org/docs/Web/API/RequestInit | RequestInit} for more details.
   */
  delete(relativePath: string, init?: RequestInit): Promise<Response>;

  /**
   * Upload a file to the server.
   *
   * @param relativePath - Upload endpoint relative path.
   * @param file - {@link https://developer.mozilla.org/docs/Web/API/File | Web API File} object are
   *   generally retrieved from a {@link https://developer.mozilla.org/docs/Web/API/FileList | FileList}
   *   object returned as a result of a user selecting files using the HTML `<input>` element.
   * @param onProgress - Upload progress callback.
   * @param init - A set of options that can be used to configure a fetch request. See
   *   {@link https://developer.mozilla.org/docs/Web/API/RequestInit | RequestInit} for more details.
   */
  uploadFile(
    relativePath: string,
    file: globalThis.File,
    onProgress?: (progress: number) => void,
    init?: RequestInit
  ): Promise<XMLHttpRequest>;

  /**
   * Downloads the specified file from the server.
   *
   * @param relativePath - Download endpoint relative path.
   * @param onProgress - Download progress callback.
   * @param init - A set of options that can be used to configure a fetch request. See
   *   {@link https://developer.mozilla.org/docs/Web/API/RequestInit | RequestInit} for more details.
   */
  downloadFile(
    relativePath: string,
    onProgress?: (progress: number, chunk: Uint8Array) => void,
    init?: RequestInit
  ): Promise<Response>;

  /**
   * Downloads a part of file from the server.
   *
   * @param relativePath - Download endpoint relative path.
   * @param reserved - Reserved, do not use.
   * @param ranges - Ranges of resource file contents to download. See
   *   {@link https://developer.mozilla.org/docs/Web/HTTP/Guides/Range_requests | HTTP range requests} for
   *   more details.
   * @param onProgress - Download progress callback.
   * @param init - A set of options that can be used to configure a fetch request. See
   *   {@link https://developer.mozilla.org/docs/Web/API/RequestInit | RequestInit} for more details.
   */
  downloadFileRange(
    relativePath: string,
    reserved: number | string,
    ranges: Array<{ begin: number; end: number; requestId: number }>,
    onProgress?: (progress: number, chunk: Uint8Array, requestId: number) => void,
    init?: RequestInit
  ): Promise<Response>;
}