@cubicweb/client 3.0.0-alpha.9 → 3.0.0

package/package.json

@@ -2,12 +2,10 @@
   "name": "@cubicweb/client",
   "description": "Official JS client for CubicWeb API",
   "author": "Logilab",
-  "version": "3.0.0-alpha.9",
+  "version": "3.0.0",
   "license": "LGPL-3.0-or-later",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "scripts": {
-    "build": "run -T tsc  --project tsconfig.build.json",
+    "build": "run -T tsc --project tsconfig.build.json",
     "docs": "run -T typedoc"
   },
   "repository": {
@@ -23,5 +21,17 @@
     "lib/**",
     "src/**",
     "!**/__tests__/**"
-  ]
+  ],
+  "dependencies": {
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/uuid": "^9.0.8"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js",
+    "./authenticators/SignedRequestAuthenticator": "./lib/api/authenticators/SignedRequestAuthenticator.js",
+    "./authenticators/CookieAuthenticator": "./lib/api/authenticators/CookieAuthenticator.js"
+  }
 }

package/src/Authenticator.ts

@@ -0,0 +1,8 @@
+export interface AuthenticatedRequest {
+  url: string;
+  init: RequestInit;
+}
+
+export interface Authenticator {
+  authenticate(url: string, init: RequestInit): Promise<AuthenticatedRequest>;
+}

package/src/api/Api.ts

@@ -1,46 +1,42 @@
-import { ValidationError } from "../Errors";
-import { RawSchema } from "../schema/raw/Schema";
+import type { Authenticator } from "../Authenticator.js";
+import { ValidationError } from "../errors.js";
+import { RawSchema } from "../schema/raw/Schema.js";
+import { getBinariesFromTransaction, serializeQueryParams } from "../utils.js";
+import { RQLBinary } from "./binary/RQLBinary.js";
+import { RQLQueryCellRef } from "./query/references.js";
+import { Transaction } from "./transaction/Transaction.js";
 import {
+  RawTransactionResult,
   TransactionResult,
-  Transaction,
-  TransactionQueryScalarRef,
-  TransactionQueryBinaryRef,
-} from "./Transaction";
+} from "./transaction/TransactionResult.js";
+
+interface ApiOptions {
+  authenticator?: Authenticator;
+}
 
 /**
- * Type representing an RQL request and its associated parameters.
+ * Type representing valid final values to use as parameters in a RQL query.
+ *
+ * For references to requests/binaries, see {@link RQLQueryCellRef} and {@link RQLQueryBinaryRef}
  *
  * @category Api
  */
-export type RQLQuery = [string, RQLParams];
+export type RQLQueryParamValue = string | number | boolean | null;
 
-export type RQLParamValue = string | number | boolean | null;
 /**
  * Type representing RQL parameters to send along a request.
  *
+ * Each key must be referenced in the RQL query.
+ *
  * @category Api
  */
-export type RQLParams = Record<
+export type RQLQueryParams = Record<
   string,
-  RQLParamValue | TransactionQueryScalarRef | TransactionQueryBinaryRef
+  RQLQueryParamValue | RQLQueryCellRef | RQLBinary
 >;
 
 /**
- * Type representing a row returned in a result set.
- *
- * @category Api
- */
-export type RqlRow = Array<string | number | boolean | null>;
-
-/**
- * Type representing a RQL request result.
- *
- * @category Api
- */
-export type ResultSet = Array<RqlRow>;
-
-/**
- * Type representing the currently logged user's data
+ * Type representing the currently logged user's data as returned by the `/current-user` route
  *
  * @category Api
  */
@@ -64,6 +60,9 @@ type ApiError = {
 /**
  * Type representing the error data sent to clients when retrieving an API error.
  *
+ * It simply adds the HTTP status code in a `status` key to the regular CubicWeb api error,
+ * so users can handle HTTP status codes in their code.
+ *
  * @category Api
  */
 export type ApiErrorResponse = {
@@ -74,7 +73,7 @@ export type ApiErrorResponse = {
  * Class used to handle requests to the CubicWeb API.
  *
  * You should never have to create this object yourself.
- * Instead, retrieve this object from the methods in the `Client` class.
+ * Instead, retrieve this object from the methods in the {@link Client} class.
  *
  * @internal
  */
@@ -87,18 +86,19 @@ export default class Api {
   private _logoutApiUrl: string;
   private _currentUserApiUrl: string;
   private _binaryApiUrl: string;
+  private _authenticator?: Authenticator;
 
   /**
    * Class used to handle requests to the CubicWeb API.
    *
    * You should never have to create this object yourself.
-   * Instead, retrieve this object from the methods in the `Client` class.
+   * Instead, retrieve this object from the methods in the {@link Client} class.
    *
    * @param apiUrl The API url. It should not include the API version as it will be automatically added.
    * Example: if you can retrieve the schema with https://example.com/api/v1/schema,
    * use https://example.com/api as `apiUrl`.
    */
-  constructor(apiUrl: string) {
+  constructor(apiUrl: string, options: ApiOptions) {
     this._apiUrl = apiUrl;
     this._rqlApiUrl = this.getApiRoute("rql");
     this._schemaApiUrl = this.getApiRoute("schema");
@@ -106,6 +106,7 @@ export default class Api {
     this._logoutApiUrl = this.getApiRoute("logout");
     this._currentUserApiUrl = this.getApiRoute("current-user");
     this._binaryApiUrl = this.getApiRoute("binary");
+    this._authenticator = options.authenticator;
   }
 
   get apiUrl() {
@@ -122,9 +123,8 @@ export default class Api {
    * @returns The CubicWeb instance's JSON schema.
    */
   async schema(): Promise<RawSchema> {
-    return nonNullFetchApi<RawSchema>(this._schemaApiUrl, {
+    return this.nonNullFetchApi<RawSchema>(this._schemaApiUrl, {
       method: "GET",
-      credentials: "include",
     });
   }
 
@@ -132,18 +132,17 @@ export default class Api {
    * Tries to log in the user on the configured CubicWeb instance with the given credentials.
    *
    * @param login The user login
-   * @param password THe user password
+   * @param password The user password
    * @returns A promise returning true if the login was successful, false otherwise
    */
   async login(login: string, password: string): Promise<boolean> {
     try {
-      await fetchApi<null>(this._loginApiUrl, {
+      await this.fetchApi<null>(this._loginApiUrl, {
         method: "POST",
         body: JSON.stringify({
           login,
           password,
         }),
-        credentials: "include",
       });
       return true;
     } catch (_error) {
@@ -157,9 +156,8 @@ export default class Api {
    * @returns A promise which will resolve when the user is properly logged out
    */
   async logout(): Promise<void> {
-    await fetchApi<null>(this._logoutApiUrl, {
+    await this.fetchApi<null>(this._logoutApiUrl, {
       method: "POST",
-      credentials: "include",
     });
   }
 
@@ -169,32 +167,42 @@ export default class Api {
    * @returns A promise resolving to the current user
    */
   async currentUser(): Promise<CurrentUser> {
-    return await nonNullFetchApi<CurrentUser>(this._currentUserApiUrl, {
+    return await this.nonNullFetchApi<CurrentUser>(this._currentUserApiUrl, {
       method: "GET",
-      credentials: "include",
     });
   }
 
   /**
    * Get the binary for the given entity attribute
    *
-   * @returns A promise resolving to the binary
+   * @param eid Entity eid to fetch the binary from
+   * @param attribute Attribute on the entity in which the binary is stored
+   * @returns A promise resolving to the binary as a Blob
    */
   async binary(eid: number, attribute: string): Promise<Blob> {
     const params = new URLSearchParams({
       eid: eid.toString(),
       attribute,
     });
-    return await nonNullFetchApi<Blob>(this._binaryApiUrl + params, {
+    return await this.nonNullFetchApi<Blob>(this._binaryApiUrl + params, {
       method: "GET",
-      credentials: "include",
     });
   }
 
+  /**
+   * Executes the given transaction.
+   *
+   * If the {@link Transaction} object contains binaries, the request is automatically
+   * sent using `multipart/form-data` to allow uploading binaries.
+   *
+   * @param transaction Transaction to execute
+   * @returns A promise returning the transaction result on success
+   */
   async rql(transaction: Transaction): Promise<TransactionResult> {
+    const binaries = getBinariesFromTransaction(transaction);
     try {
-      if (Object.keys(transaction.binaries).length > 0) {
-        return await this.multipartTransaction(transaction);
+      if (binaries.length > 0) {
+        return await this.multipartTransaction(transaction, binaries);
       } else {
         return await this.jsonTransaction(transaction);
       }
@@ -204,44 +212,42 @@ export default class Api {
   }
 
   private getTransactionParams(transaction: Transaction) {
-    return transaction.queries.map((transactionQuery) => ({
-      query: transactionQuery.query,
-      params: transactionQuery.params,
+    return transaction.queries.map((rqlQuery) => ({
+      query: rqlQuery.rql,
+      params: serializeQueryParams(transaction, rqlQuery.params),
     }));
   }
 
-  private async multipartTransaction(transaction: Transaction) {
+  private async multipartTransaction(
+    transaction: Transaction,
+    binaries: RQLBinary[]
+  ) {
     const jsonParams = this.getTransactionParams(transaction);
     const formData = new FormData();
     formData.append("queries", JSON.stringify(jsonParams));
-    Object.entries(transaction.binaries).forEach(([key, value]) => {
-      formData.append(key, value);
+    binaries.forEach((binary) => {
+      formData.append(binary.uuid, binary.blob);
     });
 
-    const resultSets = await nonNullFetchApi<ReadonlyArray<ResultSet>>(
+    const resultSets = await this.nonNullFetchApi<RawTransactionResult>(
       this._rqlApiUrl,
       {
         method: "POST",
-        credentials: "include",
         body: formData,
-        headers: {
-          "Content-Type": "multipart/form-data",
-        },
       }
     );
-    return new TransactionResult(resultSets);
+    return new TransactionResult(transaction, resultSets);
   }
 
   private async jsonTransaction(transaction: Transaction) {
-    const resultSets = await nonNullFetchApi<ReadonlyArray<ResultSet>>(
+    const resultSets = await this.nonNullFetchApi<RawTransactionResult>(
       this._rqlApiUrl,
       {
         method: "POST",
-        credentials: "include",
         body: JSON.stringify(this.getTransactionParams(transaction)),
       }
     );
-    return new TransactionResult(resultSets);
+    return new TransactionResult(transaction, resultSets);
   }
 
   private handleUserErrors(error: unknown): never {
@@ -260,79 +266,96 @@ export default class Api {
     }
     throw error;
   }
-}
 
-/**
- * Behaves the same as `fetchAPI` but forbids null responses.
- * If this function detects a null response from the API,
- * the promise will be rejected with a 500 error code.
- *
- * @param input The API route to use
- * @param init Additional request parameters
- * @returns A promise with the non-null fetched result
- */
-async function nonNullFetchApi<R = unknown>(
-  input: RequestInfo,
-  init?: RequestInit
-) {
-  const result = await fetchApi<R>(input, init);
-  if (result == null) {
-    const error: ApiErrorResponse = {
-      status: 500,
-      title: "Unexpected null response",
-      message: "Response was null but a value was expected",
-    };
-    throw error;
+  /**
+   * Behaves the same as `fetchAPI` but forbids null responses.
+   * If this function detects a null response from the API,
+   * the promise will be rejected with a 500 error code.
+   *
+   * @param input The API route to use
+   * @param init Additional request parameters
+   * @returns A promise with the non-null fetched result
+   */
+  private async nonNullFetchApi<R = unknown>(url: string, init: RequestInit) {
+    const result = await this.fetchApi<R>(url, init);
+    if (result == null) {
+      const error: ApiErrorResponse = {
+        status: 500,
+        title: "Unexpected null response",
+        message: "Response was null but a value was expected",
+      };
+      throw error;
+    }
+    return result;
   }
-  return result;
-}
 
-/**
- * Sends a request to the given API route with the `Content-Type` header set and waits for a response.
- * The returned promise will be rejected if the API returns HTTP error codes.
- * The rejected promise will contain an `ApiErrorResponse` object.
- *
- * @param input The API route to use
- * @param init Additional request parameters
- * @returns A promise with the fetched result
- */
-async function fetchApi<R = unknown>(
-  input: RequestInfo,
-  init?: RequestInit
-): Promise<R | null> {
-  let headers = init?.headers;
-  if (init?.method && init.method !== "GET") {
-    headers = {
-      "Content-Type": "application/json;charset=UTF-8",
-      // CSRF custom header necessary for POST requests
-      "X-Client-Name": "XMLHttpRequest",
-      ...init?.headers,
-    };
-  }
+  /**
+   * Sends a request to the given API route with the `Content-Type` header set and waits for a response.
+   * The returned promise will be rejected if the API returns HTTP error codes.
+   * The rejected promise will contain an `ApiErrorResponse` object.
+   *
+   * @param input The API route to use
+   * @param init Additional request parameters
+   * @returns A promise with the fetched result
+   */
+  private async fetchApi<R = unknown>(
+    url: string,
+    init: RequestInit
+  ): Promise<R | null> {
+    const headers = new Headers(init.headers);
 
-  const response = await fetch(input, {
-    ...init,
-    headers,
-  });
-  const status = response.status;
-  if (status >= 200 && status < 300) {
-    if (status === 204) {
-      return null;
+    // Add custom header  used as CSRF protection
+    // note: it is only necessary for non GET requests but can also be useful
+    // while debugging.
+    if (!headers.has("X-Client-Name")) {
+      headers.append("X-Client-Name", "XMLHttpRequest");
     }
-    try {
-      return await response.json();
-    } catch (e) {
-      console.error(e);
-      return null;
+
+    // Add a "Content-Type" header whenever a body is passed.
+    // The header might already have been set (either by the caller of this
+    // function or by and encoder)
+    if (
+      init.body &&
+      !headers.has("Content-Type") &&
+      !(init.body instanceof FormData)
+    ) {
+      headers.append("Content-Type", "application/json;charset=UTF-8");
     }
-  } else {
-    let json;
-    try {
-      json = await response.json();
-    } catch (e) {
-      console.error(e);
-      throw { status, title: "Error", message: "" };
+    init.headers = headers;
+    // Authenticate request
+    if (this._authenticator) {
+      const authenticatedRequest = await this._authenticator.authenticate(
+        url,
+        init
+      );
+      url = authenticatedRequest.url;
+      init = authenticatedRequest.init;
+    }
+
+    // Execute request
+    const response = await fetch(url, init);
+
+    // Parse response body and handle errors
+    const status = response.status;
+    if (status >= 200 && status < 300) {
+      if (status === 204) {
+        return null;
+      }
+      try {
+        return await response.json();
+      } catch (e) {
+        console.error(e);
+        return null;
+      }
+    } else {
+      let json;
+      try {
+        json = await response.json();
+      } catch (e) {
+        console.error(e);
+        throw { status, title: "Error", message: "" };
+      }
+      throw { status, ...json };
     }
-    throw { status, ...json };
   }
 }

package/src/api/Client.ts

@@ -1,6 +1,14 @@
-import { Schema } from "../schema/classes/Schema";
-import Api, { RQLParams, ResultSet, CurrentUser } from "./Api";
-import { BinariesParam, Transaction, TransactionResult } from "./Transaction";
+import { Authenticator } from "../Authenticator.js";
+import { Schema } from "../schema/classes/Schema.js";
+import Api, { RQLQueryParams, CurrentUser } from "./Api.js";
+import { ResultSet } from "./ResultSet.js";
+import { RQLQuery } from "./query/RQLQuery.js";
+import { Transaction } from "./transaction/Transaction.js";
+import { TransactionResult } from "./transaction/TransactionResult.js";
+
+export interface ClientOptions {
+  authenticator?: Authenticator;
+}
 
 /**
  * Class used to communicate with a CubicWeb instance's API.
@@ -9,7 +17,6 @@ import { BinariesParam, Transaction, TransactionResult } from "./Transaction";
  */
 export default class Client {
   private api: Api;
-
   /**
    * Class used to communicate with a CubicWeb instance's API.
    *
@@ -17,8 +24,8 @@ export default class Client {
    * Example: if you can retrieve the schema with https://example.com/api/v1/schema,
    * use https://example.com/api as `apiUrl`.
    */
-  constructor(apiUrl: string) {
-    this.api = new Api(apiUrl);
+  constructor(apiUrl: string, options?: ClientOptions) {
+    this.api = new Api(apiUrl, options ?? {});
   }
 
   get apiUrl() {
@@ -28,20 +35,19 @@ export default class Client {
   /**
    * Executes the given query and waits for the response.
    *
-   * @param query The RQL query to send
+   * If binaries are given, the request is automatically
+   * sent using `multipart/form-data` to allow uploading binaries.
+   *
+   * @param rql The RQL query to send
    * @param params The additional parameters for the request
    * @returns A promise with the request's result set
    */
-  async execute(
-    query: string,
-    params: RQLParams = {},
-    binaries?: BinariesParam
-  ): Promise<ResultSet> {
+  async execute(rql: string, params: RQLQueryParams = {}): Promise<ResultSet> {
     const transaction = new Transaction();
-    const transactionQuery = transaction.push(query, params);
-    transaction.setBinaries(binaries);
+    const query = new RQLQuery(rql, params);
+    transaction.push(query);
     const result = await this.executeTransaction(transaction);
-    return result.resolveQuery(transactionQuery.ref());
+    return result.getResultSet(query);
   }
 
   /**
@@ -58,7 +64,7 @@ export default class Client {
    * Tries to log in the user on the configured CubicWeb instance with the given credentials.
    *
    * @param login The user login
-   * @param password THe user password
+   * @param password The user password
    * @returns A promise returning true if the login was successful, false otherwise
    */
   async login(login: string, password: string) {
@@ -84,8 +90,13 @@ export default class Client {
   }
 
   /**
+   * Executes the given transaction.
+   *
+   * If the {@link Transaction} object contains binaries, the request is automatically
+   * sent using `multipart/form-data` to allow uploading binaries.
+   *
    * @param transaction Transaction to execute
-   * @returns A promise fulfilled when the transaction is completed
+   * @returns A promise returning the transaction result on success
    */
   async executeTransaction(
     transaction: Transaction
@@ -96,7 +107,9 @@ export default class Client {
   /**
    * Get the binary for the given entity attribute
    *
-   * @returns A promise resolving to the binary
+   * @param eid Entity eid to fetch the binary from
+   * @param attribute Attribute on the entity in which the binary is stored
+   * @returns A promise resolving to the binary as a Blob
    */
   async getBinary(eid: number, attribute: string) {
     return await this.api.binary(eid, attribute);

package/src/api/ResultSet.ts

@@ -0,0 +1,95 @@
+/**
+ * Interface representing the json returned by the API for a single result set
+ *
+ * @category Api
+ */
+export interface RawResultSet {
+  readonly rows: ResultSetCell[][];
+  readonly column_names: string[];
+}
+
+/**
+ * Interface representing the json returned by the API for a single row in a result set
+ *
+ * @category Api
+ */
+export type RawResultSetRow = ResultSetCell[];
+
+/**
+ * Type representing a final value in a result set.
+ *
+ * Please not this type may not be accurate if you use entity methods,
+ * as those methods may return any data structure.
+ *
+ * @category Api
+ */
+export type ResultSetCell = string | number | boolean | null;
+
+/**
+ * Class representing a row returned in a result set.
+ *
+ * @category Api
+ */
+export class ResultSetRow implements Iterable<ResultSetCell> {
+  constructor(
+    public readonly columnNames: string[],
+    private readonly cells: RawResultSetRow
+  ) {}
+
+  *[Symbol.iterator]() {
+    for (const cell of this.cells) {
+      yield cell;
+    }
+  }
+
+  get length() {
+    return this.cells.length;
+  }
+
+  getCell(column: number | string) {
+    if (typeof column === "number") {
+      return this.cells[column];
+    } else {
+      const columnIndex = this.columnNames.indexOf(column);
+      return this.cells[columnIndex];
+    }
+  }
+}
+
+/**
+ * Class representing a RQL request result.
+ *
+ * @category Api
+ */
+export class ResultSet {
+  public readonly columnNames: string[];
+  readonly #rows: RawResultSetRow[];
+
+  constructor(rawResultSet: RawResultSet) {
+    this.columnNames = rawResultSet.column_names;
+    this.#rows = rawResultSet.rows;
+  }
+
+  *[Symbol.iterator]() {
+    for (const r of this.#rows) {
+      yield new ResultSetRow(this.columnNames, r);
+    }
+  }
+
+  get length() {
+    return this.#rows.length;
+  }
+
+  getRow(row: number): ResultSetRow {
+    return new ResultSetRow(this.columnNames, this.#rows[row]);
+  }
+
+  getCell(row: number, column: number | string): ResultSetCell {
+    if (typeof column === "number") {
+      return this.#rows[row][column];
+    } else {
+      const columnIndex = this.columnNames.indexOf(column);
+      return this.#rows[row][columnIndex];
+    }
+  }
+}

package/src/api/authenticators/CookieAuthenticator.ts

@@ -0,0 +1,17 @@
+import { AuthenticatedRequest, Authenticator } from "../../Authenticator.js";
+
+export interface CookieAuthenticatorOptions {
+  credentials?: RequestCredentials;
+}
+
+export class CookieAuthenticator implements Authenticator {
+  constructor(private options?: CookieAuthenticatorOptions) {}
+
+  async authenticate(
+    url: string,
+    init: RequestInit
+  ): Promise<AuthenticatedRequest> {
+    const credentials = this.options?.credentials;
+    return { url, init: { ...init, credentials } };
+  }
+}