@cubicweb/client 3.0.0-alpha.8 → 3.0.0

package/README.md

@@ -7,11 +7,12 @@ library.
 
 The full documentation is available [here](https://cubicweb.pages.logilab.fr/cubicwebjs/client).
 
-**Compatible with [API cube](https://forge.extranet.logilab.fr/cubicweb/cubes/api) version 0.13 only.**
+**Compatible with [API cube](https://forge.extranet.logilab.fr/cubicweb/cubes/api) version 0.15 only.**
 
 ## Installation
 
 @cubicweb/client is available from NPM:
+
 ```bash
 # With NPM
 npm i @cubicweb/client
@@ -29,7 +30,7 @@ This class requires the URL to your CubicWeb instance API endpoint
 (eg: `https://example.com/api`).
 
 ```js
-const client = new Client("https://example.com/api")
+const client = new Client("https://example.com/api");
 ```
 
 **⚠️ Real API routes include the API version in the URL (eg: `v1`),
@@ -77,24 +78,18 @@ client
       });
 
     // Execute a series of request in a transaction
-    const transaction = new Transaction()
-    transaction.push({
-      query: `INSERT Person X: X name "test"`
-    })
-    transaction.push({
-      query: `Any X Where X eid %(created_eid)s`,
-      params: {
-          created_eid: {
-            queryIndex: 0,
-            row: 0,
-            column: 0,
-          } 
-        }
-    })
+    const transaction = new Transaction();
+    const insertQuery = new RQLQuery(`INSERT Person X: X name "test"`);
+    transaction.push(insertQuery);
+    transaction.push(
+      new RQLQuery(`INSERT Person X: X name "test"`, {
+        created_eid: insertQuery.cellRef(0, 0),
+      })
+    );
     client
       .executeTransaction(transaction)
       .then((callbackResult) => {
-        console.log("Transaction was successul and the callback returned:");
+        console.log("Transaction was successful and the callback returned:");
         console.log(callbackResult);
       })
       .catch((e) => {
@@ -122,36 +117,64 @@ you must authorize the URL the client is running on as well as the `Content-Type
 
 ## Authentication
 
-The API cube uses cookie authentication using [JWT](https://jwt.io).
-A `CW_JWT` [HTTP Only](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#security) cookie
-will be automatically created by the browser when executing the login request.
-This cookie cannot be accessed by the JavaScript so you will have to implement your own
-logic to save the login state.
+The API cube uses a cookie authentication method by default. When you call the login route, the cookie will be automatically created by the browser.
 
 If the client is running on a different server from your CubicWeb instance,
 make sure you setup CORS as described above.
 For the login to work, you may also need to modify the cookie sent by the API cube to set
 [`SameSite`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#samesite_attribute)
-to `None`. 
+to `None`.
+
+You can use other authenticators if needed. Here is an example relying on the
+[`cubicweb-signedrequest`](https://forge.extranet.logilab.fr/cubicweb/cubes/signedrequest)
+cube (v3.x):
+
+```typescript
+import { Client } from "@cubicweb/client";
+import { SignedRequestAuthenticator } from "@cubicweb/client/authenticators/SignedRequestAuthenticator";
+
+const authenticator = new SignedRequetAuthenticator({
+  id: "<token-id>",
+  token: "<token>",
+});
+const client = new Client(API_URL, { authenticator });
+```
+
+You can also provide your own authenticator by implementing the `Authenticator` interface:
+
+```typescript
+import { Authenticator, Client } from "@cubicweb/client";
+
+const client = new Client(API_URL, {
+  authenticator: {
+    authenticate(info, init) {
+      const headers = new Headers(init.headers);
+      headers.append("Authorization", `Basic Zm9vOmJhcg==`);
+      return { info, init: { ...init, headers } };
+    },
+  },
+});
+```
 
 ## Using the Schema
 
 This library provides CubicWeb [schema abstraction classes](packages/client/src/schema/Schema.ts). Three classes are available:
-* `Schema` - Global handling of the schema.
-Can be used to query entities and relations.
-* `EntitySchema` - Handling of a single entity type.
-Can be used to query relations and metadata about the entity.
-* `RelationDefinitionSchema` - Handling of a single relation.
-Can be used to retrieve associated entities and metadata the relation.
+
+- `Schema` - Global handling of the schema.
+  Can be used to query entities and relations.
+- `EntitySchema` - Handling of a single entity type.
+  Can be used to query relations and metadata about the entity.
+- `RelationDefinitionSchema` - Handling of a single relation.
+  Can be used to retrieve associated entities and metadata the relation.
 
 The `Schema` class is created from the JSON schema returned by the API.
 The `Client.schema()` method takes care of this for you.
 If your schema does not change often, it is recommended to export it using the following command
-(replace `<YOUR_INSTANCE_NAME>` by the name of your instance): 
+(replace `<YOUR_INSTANCE_NAME>` by the name of your instance):
 
 ```bash
 cubicweb-ctl export-schema -f json <YOUR_INSTANCE_NAME>
-``` 
+```
 
 You can then manually create the Schema object by passing your JSON schema to its constructor.
 
@@ -161,6 +184,7 @@ const schema = client.schema();
 // Using a local json schema
 const schema = new Schema(your_raw_json_schema);
 ```
+
 `EntitySchema` and `RelationDefinitionSchema` objects should not be created manually.
 These are returned when querying a `Schema` object.
 
@@ -187,7 +211,7 @@ to benefit from the strong type inference. You can generate this representation
 
 ```bash
 cubicweb-ctl export-schema -f typescript <YOUR_INSTANCE_NAME>
-``` 
+```
 
 This command will generate a file `schema.ts` containing the typings.
 You can then include it in your project. When using this generated type,
@@ -195,7 +219,7 @@ the TS engine will be able to detect invalid entity types and relations.
 
 **⚠️ You cannot type the schema when using the `client.schema()` method.
 This is intended to prevent errors if the JSON schema changes and not the TS schema.**
-You must export both the JSON schema and TypeScript schema to use the typings. 
+You must export both the JSON schema and TypeScript schema to use the typings.
 
 ```js
 // Type the schema when creating from a local JSON schema
@@ -210,7 +234,7 @@ const entity = schema.getEntity("ValidEntityType");
 ## Contribute
 
 All `@cubicweb` libraries are in the [cubicwebjs monorepo](https://forge.extranet.logilab.fr/cubicweb/cubicwebjs).
-Please refer to the main README. 
+Please refer to the main README.
 
 ## Get Help
 

package/lib/Authenticator.d.ts

@@ -0,0 +1,8 @@
+export interface AuthenticatedRequest {
+    url: string;
+    init: RequestInit;
+}
+export interface Authenticator {
+    authenticate(url: string, init: RequestInit): Promise<AuthenticatedRequest>;
+}
+//# sourceMappingURL=Authenticator.d.ts.map

package/lib/Authenticator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Authenticator.d.ts","sourceRoot":"","sources":["../src/Authenticator.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC7E"}

package/lib/Authenticator.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Authenticator.js.map

package/lib/Authenticator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Authenticator.js","sourceRoot":"","sources":["../src/Authenticator.ts"],"names":[],"mappings":""}

package/lib/api/Api.d.ts

@@ -1,32 +1,30 @@
-import { RawSchema } from "../schema/raw/Schema";
-import { TransactionResult, Transaction, TransactionQueryScalarRef, TransactionQueryBinaryRef } from "./Transaction";
+import type { Authenticator } from "../Authenticator.js";
+import { RawSchema } from "../schema/raw/Schema.js";
+import { RQLBinary } from "./binary/RQLBinary.js";
+import { RQLQueryCellRef } from "./query/references.js";
+import { Transaction } from "./transaction/Transaction.js";
+import { TransactionResult } 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.
  *
- * @category Api
- */
-export type RQLQuery = [string, RQLParams];
-export type RQLParamValue = string | number | boolean | null;
-/**
- * Type representing RQL parameters to send along a request.
+ * For references to requests/binaries, see {@link RQLQueryCellRef} and {@link RQLQueryBinaryRef}
  *
  * @category Api
  */
-export type RQLParams = Record<string, RQLParamValue | TransactionQueryScalarRef | TransactionQueryBinaryRef>;
+export type RQLQueryParamValue = string | number | boolean | null;
 /**
- * Type representing a row returned in a result set.
+ * Type representing RQL parameters to send along a request.
  *
- * @category Api
- */
-export type RqlRow = Array<string | number | boolean | null>;
-/**
- * Type representing a RQL request result.
+ * Each key must be referenced in the RQL query.
  *
  * @category Api
  */
-export type ResultSet = Array<RqlRow>;
+export type RQLQueryParams = Record<string, RQLQueryParamValue | RQLQueryCellRef | RQLBinary>;
 /**
- * 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
  */
@@ -48,6 +46,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 = {
@@ -57,7 +58,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
  */
@@ -70,17 +71,18 @@ export default class Api {
     private _logoutApiUrl;
     private _currentUserApiUrl;
     private _binaryApiUrl;
+    private _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);
     get apiUrl(): string;
     private getApiRoute;
     /**
@@ -93,7 +95,7 @@ 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
      */
     login(login: string, password: string): Promise<boolean>;
@@ -112,14 +114,45 @@ export default class Api {
     /**
      * 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
      */
     binary(eid: number, attribute: string): Promise<Blob>;
+    /**
+     * 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
+     */
     rql(transaction: Transaction): Promise<TransactionResult>;
     private getTransactionParams;
     private multipartTransaction;
     private jsonTransaction;
     private handleUserErrors;
+    /**
+     * 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 nonNullFetchApi;
+    /**
+     * 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 fetchApi;
 }
 export {};
 //# sourceMappingURL=Api.d.ts.map

package/lib/api/Api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Api.d.ts","sourceRoot":"","sources":["../../src/api/Api.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,yBAAyB,EACzB,yBAAyB,EAC1B,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAE3C,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAC7D;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAC5B,MAAM,EACN,aAAa,GAAG,yBAAyB,GAAG,yBAAyB,CACtE,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;AAEtC;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,KAAK,QAAQ,GAAG;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,QAAQ,CAAC;AAEb;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,GAAG;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;;;;;OASG;gBACS,MAAM,EAAE,MAAM;IAU1B,IAAI,MAAM,WAET;IAED,OAAO,CAAC,WAAW;IAInB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC;IAOlC;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgB9D;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAO7B;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC;IAOzC;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrD,GAAG,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAY/D,OAAO,CAAC,oBAAoB;YAOd,oBAAoB;YAmBpB,eAAe;IAY7B,OAAO,CAAC,gBAAgB;CAgBzB"}
+{"version":3,"file":"Api.d.ts","sourceRoot":"","sources":["../../src/api/Api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAEL,iBAAiB,EAClB,MAAM,oCAAoC,CAAC;AAE5C,UAAU,UAAU;IAClB,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CACjC,MAAM,EACN,kBAAkB,GAAG,eAAe,GAAG,SAAS,CACjD,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,KAAK,QAAQ,GAAG;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,QAAQ,CAAC;AAEb;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,OAAO,GAAG;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,cAAc,CAAC,CAAgB;IAEvC;;;;;;;;;OASG;gBACS,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU;IAW/C,IAAI,MAAM,WAET;IAED,OAAO,CAAC,WAAW;IAInB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC;IAMlC;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAe9D;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC;IAMzC;;;;;;OAMG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3D;;;;;;;;OAQG;IACG,GAAG,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAa/D,OAAO,CAAC,oBAAoB;YAOd,oBAAoB;YAqBpB,eAAe;IAW7B,OAAO,CAAC,gBAAgB;IAiBxB;;;;;;;;OAQG;YACW,eAAe;IAa7B;;;;;;;;OAQG;YACW,QAAQ;CA4DvB"}