@cubicweb/client 1.4.0 → 1.5.0

package/lib/schema/raw/Constraints.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Base type used to describe a constraint.
+ */
+declare type ConstraintBase<T extends string, V extends Record<string, unknown> | null> = {
+    type: T;
+    value: V;
+};
+/**
+ * All the possible operators inside a constraint.
+ */
+export declare type ConstraintOperator = ">" | ">=" | "<" | "<=";
+/**
+ * THe type of a constraint message when one is present.
+ */
+declare type ConstraintMessage = string | null;
+export declare type UniqueConstraint = ConstraintBase<"UniqueConstraint", null>;
+export declare type SizeConstraint = ConstraintBase<"SizeConstraint", {
+    min: number | null;
+    max: number | null;
+    msg: ConstraintMessage;
+}>;
+export declare type RegexpConstraint = ConstraintBase<"RegexpConstraint", {
+    regexp: string;
+    flags: number;
+    msg: ConstraintMessage;
+}>;
+export declare type BoundaryConstraint = ConstraintBase<"BoundaryConstraint", {
+    boundary: number | null;
+    op: ConstraintOperator;
+    msg: ConstraintMessage;
+}>;
+export declare type IntervalBoundConstraint = ConstraintBase<"IntervalBoundConstraint", {
+    minvalue: number | null;
+    maxvalue: number | null;
+    msg: ConstraintMessage;
+}>;
+export declare type StaticVocabularyConstraint = ConstraintBase<"StaticVocabularyConstraint", {
+    values: string[];
+    msg: ConstraintMessage;
+}>;
+export declare type FormatConstraint = ConstraintBase<"FormatConstraint", {
+    values: ["text/rest", "text/markdown", "text/html", "text/plain"];
+    msg: ConstraintMessage;
+}>;
+export declare type RQLVocabularyConstraint = ConstraintBase<"RQLVocabularyConstraint", {
+    expression: string;
+    mainvars: string[];
+}>;
+/**
+ * Type representing all possible constraints for attributes.
+ */
+export declare type AttributeConstraint = Readonly<UniqueConstraint | SizeConstraint | RegexpConstraint | BoundaryConstraint | IntervalBoundConstraint | StaticVocabularyConstraint | FormatConstraint>;
+/**
+ * Type representing all possible constraints for relations.
+ */
+export declare type RelationConstraint = Readonly<RQLVocabularyConstraint>;
+export {};
+//# sourceMappingURL=Constraints.d.ts.map

package/lib/schema/raw/Constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Constraints.d.ts","sourceRoot":"","sources":["../../../src/schema/raw/Constraints.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,aAAK,cAAc,CACjB,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,IACtC;IACF,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,CAAC,CAAC;CACV,CAAC;AAEF;;GAEG;AACH,oBAAY,kBAAkB,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;AAEzD;;GAEG;AACH,aAAK,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAAC;AAEvC,oBAAY,gBAAgB,GAAG,cAAc,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;AAExE,oBAAY,cAAc,GAAG,cAAc,CACzC,gBAAgB,EAChB;IAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CACnE,CAAC;AAEF,oBAAY,gBAAgB,GAAG,cAAc,CAC3C,kBAAkB,EAClB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC1D,CAAC;AAEF,oBAAY,kBAAkB,GAAG,cAAc,CAC7C,oBAAoB,EACpB;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,EAAE,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC5E,CAAC;AACF,oBAAY,uBAAuB,GAAG,cAAc,CAClD,yBAAyB,EACzB;IAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC7E,CAAC;AAEF,oBAAY,0BAA0B,GAAG,cAAc,CACrD,4BAA4B,EAC5B;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,CAC7C,CAAC;AAEF,oBAAY,gBAAgB,GAAG,cAAc,CAC3C,kBAAkB,EAClB;IACE,MAAM,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IAClE,GAAG,EAAE,iBAAiB,CAAC;CACxB,CACF,CAAC;AAEF,oBAAY,uBAAuB,GAAG,cAAc,CAClD,yBAAyB,EACzB;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAC3C,CAAC;AAEF;;GAEG;AACH,oBAAY,mBAAmB,GAAG,QAAQ,CACtC,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAChB,kBAAkB,GAClB,uBAAuB,GACvB,0BAA0B,GAC1B,gBAAgB,CACnB,CAAC;AAEF;;GAEG;AACH,oBAAY,kBAAkB,GAAG,QAAQ,CAAC,uBAAuB,CAAC,CAAC"}

package/lib/schema/raw/Constraints.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Constraints.js.map

package/lib/schema/raw/Constraints.js.map

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

package/lib/schema/raw/Entities.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Type representing an entity schema.
+ */
+export declare type EntityRawSchema = {
+    type: string;
+    final: boolean;
+    description: string;
+};
+/**
+ * Type representing a list of entity schemas.
+ */
+export declare type EntityRawSchemaArray = ReadonlyArray<EntityRawSchema>;
+//# sourceMappingURL=Entities.d.ts.map

package/lib/schema/raw/Entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Entities.d.ts","sourceRoot":"","sources":["../../../src/schema/raw/Entities.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,oBAAY,oBAAoB,GAAG,aAAa,CAAC,eAAe,CAAC,CAAC"}

package/lib/schema/{SchemaJSON.js → raw/Entities.js}

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=SchemaJSON.js.map
+//# sourceMappingURL=Entities.js.map

package/lib/schema/raw/Entities.js.map

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

package/lib/schema/raw/RelationDefinitions.d.ts

@@ -0,0 +1,113 @@
+import { AttributeConstraint, RelationConstraint } from "./Constraints";
+import { EntityRawSchema, EntityRawSchemaArray } from "./Entities";
+/**
+ * Type representing all the possible cardinalities in CubicWeb.
+ */
+export declare type Cardinality = "*" | "1" | "?" | "+";
+/**
+ * Type representing a cardinality pair as used in relation definitions.
+ */
+export declare type CardinalityPair = `${Cardinality}${Cardinality}`;
+/**
+ * Type used as a base to build final relation definitions with primitive types (Int, String, ...).
+ *
+ * @internal
+ */
+declare type BuildObjBase<T extends string> = {
+    object: T;
+    final: true;
+    required?: boolean;
+};
+interface StringBuildObj extends BuildObjBase<"String"> {
+    default: string | null;
+}
+interface PasswordBuildObj extends BuildObjBase<"Password"> {
+    default: string | null;
+}
+interface BytesBuildObj extends BuildObjBase<"Bytes"> {
+    default: string | null;
+}
+interface IntBuildObj extends BuildObjBase<"Int"> {
+    default: number | null;
+}
+interface BigIntBuildObj extends BuildObjBase<"BigInt"> {
+    default: number | null;
+}
+interface FloatBuildObj extends BuildObjBase<"Float"> {
+    default: number | null;
+}
+interface BooleanBuildObj extends BuildObjBase<"Boolean"> {
+    default: boolean | null;
+}
+interface DecimalBuildObj extends BuildObjBase<"Decimal"> {
+    default: number | null;
+}
+interface DateBuildObj extends BuildObjBase<"Date"> {
+    default: unknown;
+}
+interface TimeBuildObj extends BuildObjBase<"Time"> {
+    default: unknown;
+}
+interface DatetimeBuildObj extends BuildObjBase<"Datetime"> {
+    default: Date | "NOW" | "TODAY" | null;
+}
+interface TZTimeBuildObj extends BuildObjBase<"TZTime"> {
+    default: unknown;
+}
+interface TZDatetimeBuildObj extends BuildObjBase<"TZDatetime"> {
+    default: unknown;
+}
+interface IntervalBuildObj extends BuildObjBase<"Interval"> {
+    default: unknown;
+}
+/**
+ * Type allowing to link the type of an object to the type of their default values in a
+ * relation definition. It only works for final relations using primitive types.
+ *
+ * @internal
+ */
+export declare type BuildObj = Readonly<StringBuildObj | PasswordBuildObj | BytesBuildObj | IntBuildObj | BigIntBuildObj | FloatBuildObj | BooleanBuildObj | DecimalBuildObj | DateBuildObj | TimeBuildObj | DatetimeBuildObj | TZTimeBuildObj | TZDatetimeBuildObj | IntervalBuildObj>;
+/**
+ * Type representing the possible options for an attribute.
+ */
+export declare type AttributeOptions = {
+    indexed?: boolean;
+    fulltextindexed?: boolean;
+    internationalizable?: boolean;
+};
+/**
+ * Type representing the possible options for a relation definition.
+ */
+export declare type RelationOptions = {
+    symmetric?: boolean;
+    inlined?: boolean;
+    fulltext_container?: "subject" | "object";
+    composite?: "subject" | "object";
+};
+/**
+ * Type representing a relation definition schema.
+ * It can represent both attributes and relations depending on the value of Final.
+ *
+ * It can infer default values type depending on the object type if the relation is final.
+ */
+export declare type RelationDefinitionRawSchema<ESchemas extends EntityRawSchemaArray, Final extends boolean = boolean> = Readonly<{
+    type: string;
+    description: string;
+    cardinality: CardinalityPair;
+    subject: ESchemas[number]["type"];
+} & (Final extends true ? BuildObj & {
+    final: true;
+    constraints: AttributeConstraint[];
+    options: AttributeOptions;
+} : {
+    object: EntityRawSchema["type"];
+    final: false;
+    constraints: RelationConstraint[];
+    options: RelationOptions;
+})>;
+/**
+ * Type representing a list of relation definitions.
+ */
+export declare type RelationDefinitionRawSchemaArray<ESchemas extends EntityRawSchemaArray> = ReadonlyArray<RelationDefinitionRawSchema<ESchemas, boolean>>;
+export {};
+//# sourceMappingURL=RelationDefinitions.d.ts.map

package/lib/schema/raw/RelationDefinitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RelationDefinitions.d.ts","sourceRoot":"","sources":["../../../src/schema/raw/RelationDefinitions.ts"],"names":[],"mappings":"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"}

package/lib/schema/raw/RelationDefinitions.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=RelationDefinitions.js.map

package/lib/schema/raw/RelationDefinitions.js.map

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

package/lib/schema/raw/Schema.d.ts

@@ -0,0 +1,13 @@
+import { EntityRawSchemaArray } from "./Entities";
+import { RelationDefinitionRawSchemaArray } from "./RelationDefinitions";
+/**
+ * The full raw JSON schema type as returned by the API.
+ * You can export this schema from your CubicWeb instance using the command:
+ *
+ * `cubicweb-ctl export-schema -f typescript <YOUR_INSTANCE_NAME>`
+ */
+export declare type RawSchema<E extends EntityRawSchemaArray = EntityRawSchemaArray, R extends RelationDefinitionRawSchemaArray<E> = RelationDefinitionRawSchemaArray<E>> = {
+    entities: E;
+    relations_definitions: R;
+};
+//# sourceMappingURL=Schema.d.ts.map

package/lib/schema/raw/Schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Schema.d.ts","sourceRoot":"","sources":["../../../src/schema/raw/Schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,gCAAgC,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;GAKG;AACH,oBAAY,SAAS,CACnB,CAAC,SAAS,oBAAoB,GAAG,oBAAoB,EACrD,CAAC,SAAS,gCAAgC,CAAC,CAAC,CAAC,GAAG,gCAAgC,CAAC,CAAC,CAAC,IACjF;IACF,QAAQ,EAAE,CAAC,CAAC;IACZ,qBAAqB,EAAE,CAAC,CAAC;CAC1B,CAAC"}

package/lib/schema/raw/Schema.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Schema.js.map

package/lib/schema/raw/Schema.js.map

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

package/lib/schema/raw/Utils.d.ts

@@ -0,0 +1,22 @@
+import { EntityRawSchemaArray } from "./Entities";
+/**
+ * Type used to check if a schema is loosely typed.
+ * Use this to create conditional types.
+ *
+ * In the given EntityRawSchemaArray, if the entities type is a string, the schema is loosely typed.
+ * If the schema is strongly typed, the entities type would be a word (which is stricter than string).
+ */
+export declare type IsLooseSchema<E extends EntityRawSchemaArray> = string extends E[number]["type"] ? true : false;
+/**
+ * Checks if the given entity type is present in the EntityRawSchemaArray.
+ * Use this to create conditional types.
+ */
+export declare type IsETypeInStrictSchema<E extends EntityRawSchemaArray, EType extends string> = EType extends E[number]["type"] ? true : false;
+/**
+ * Type representing the entity's raw schema matching this type.
+ * This type only works for EntityRawSchemaArray with literals as "type" property.
+ */
+export declare type EntityRawSchemaByType<E extends EntityRawSchemaArray, T extends string> = E[number] extends infer ESchema ? ESchema extends {
+    type: T;
+} ? ESchema : never : never;
+//# sourceMappingURL=Utils.d.ts.map

package/lib/schema/raw/Utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Utils.d.ts","sourceRoot":"","sources":["../../../src/schema/raw/Utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;GAMG;AACH,oBAAY,aAAa,CAAC,CAAC,SAAS,oBAAoB,IACtD,MAAM,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAElD;;;GAGG;AACH,oBAAY,qBAAqB,CAC/B,CAAC,SAAS,oBAAoB,EAC9B,KAAK,SAAS,MAAM,IAClB,KAAK,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAEnD;;;GAGG;AACH,oBAAY,qBAAqB,CAC/B,CAAC,SAAS,oBAAoB,EAC9B,CAAC,SAAS,MAAM,IACd,CAAC,CAAC,MAAM,CAAC,SAAS,MAAM,OAAO,GAC/B,OAAO,SAAS;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,GACzB,OAAO,GACP,KAAK,GACP,KAAK,CAAC"}

package/lib/schema/raw/Utils.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Utils.js.map

package/lib/schema/raw/Utils.js.map

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

package/package.json

@@ -2,7 +2,7 @@
   "name": "@cubicweb/client",
   "description": "Official JS client for CubicWeb API",
   "author": "Logilab",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "license": "LGPL-3.0-or-later",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/api/Api.ts

@@ -1,58 +1,130 @@
-import { RawSchema } from "../schema/SchemaJSON";
+import { RawSchema } from "../schema/raw/Schema";
 
+/**
+ * Type representing an RQL request and its associated parameters.
+ */
 export type RQLQuery = [string, RQLParams];
 
+/**
+ * Type representing RQL parameters to send along a request.
+ */
 export interface RQLParams {
   [key: string]: string | number;
 }
 
+/**
+ * Type representing a row returned in a result set.
+ */
 export type RqlRow = Array<string | number | boolean | null>;
+
+/**
+ * Type representing a RQL request result.
+ */
 export type ResultSet = Array<RqlRow>;
+
+/**
+ * Type representing the body of an error sent by CubicWeb's API.
+ */
 type ApiError = {
   title: string;
   message: string;
   data?: Record<string, unknown>;
 };
+
+/**
+ * Type representing the error data sent to clients when retrieving an API error.
+ */
 export type ApiErrorResponse = {
   status: number;
 } & ApiError;
 
+/**
+ * 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.
+ *
+ * @internal
+ */
 export default class Api {
-  private apiUrl: string;
-  private transactionApiUrl = {
+  private _apiUrl: string;
+  private _version = "v1";
+  private _rqlApiUrl: string;
+  private _schemaApiUrl: string;
+  private _loginApiUrl: string;
+  private _transactionApiUrl = {
     begin: "",
     execute: "",
     commit: "",
     rollback: "",
   };
 
+  /**
+   * 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.
+   *
+   * @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) {
-    this.apiUrl = `${apiUrl}/v1`;
-    Object.keys(this.transactionApiUrl).forEach(
+    this._apiUrl = apiUrl;
+    this._rqlApiUrl = this.getApiRoute("rql");
+    this._schemaApiUrl = this.getApiRoute("schema");
+    this._loginApiUrl = this.getApiRoute("login");
+    Object.keys(this._transactionApiUrl).forEach(
       (k) =>
-        (this.transactionApiUrl[
-          k as keyof typeof this.transactionApiUrl
-        ] = `${this.apiUrl}/transaction/${k}`)
+        (this._transactionApiUrl[k as keyof typeof this._transactionApiUrl] =
+          this.getApiRoute(`transaction/${k}`))
     );
   }
 
+  get apiUrl() {
+    return this._apiUrl;
+  }
+
+  private getApiRoute(route: string) {
+    return `${this._apiUrl}/${this._version}/${route}`;
+  }
+
+  /**
+   * Executes the given query and waits for the response.
+   *
+   * @param query 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): Promise<ResultSet> {
-    return nonNullFetchApi<ResultSet>(`${this.apiUrl}/rql`, {
+    return nonNullFetchApi<ResultSet>(this._rqlApiUrl, {
       method: "POST",
       body: JSON.stringify({ query, params }),
       credentials: "include", // FIXME is it secure?
     });
   }
 
+  /**
+   * Retrieves the CubicWeb instance's JSON schema.
+   *
+   * @returns The CubicWeb instance's JSON schema.
+   */
   async schema(): Promise<RawSchema> {
-    return nonNullFetchApi<RawSchema>(`${this.apiUrl}/schema`, {
+    return nonNullFetchApi<RawSchema>(this._schemaApiUrl, {
       method: "GET",
       credentials: "include",
     });
   }
 
+  /**
+   * 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
+   * @returns A promise returning true if the login was successful, false otherwise
+   */
   async login(login: string, password: string): Promise<boolean> {
-    return fetchApi<null>(`${this.apiUrl}/login`, {
+    return fetchApi<null>(this._loginApiUrl, {
       method: "POST",
       body: JSON.stringify({
         login,
@@ -64,35 +136,58 @@ export default class Api {
       .catch(() => false);
   }
 
+  /**
+   * Starts a new transaction.
+   *
+   * @returns A promise with the transaction uuid
+   */
   async transactionBegin(): Promise<string> {
-    return nonNullFetchApi<string>(this.transactionApiUrl.begin, {
+    return nonNullFetchApi<string>(this._transactionApiUrl.begin, {
       method: "POST",
       credentials: "include",
     });
   }
 
+  /**
+   * Executes a RQL request as part of a transaction identified by the given uuid.
+   *
+   * @param uuid The transaction's uuid
+   * @param query The RQL query to send
+   * @param params The additional parameters for the request
+   * @returns A promise with the request's result set
+   */
   async transactionExecute(
     uuid: string,
     query: string,
     params: RQLParams
   ): Promise<ResultSet | null> {
-    return fetchApi<ResultSet>(this.transactionApiUrl.execute, {
+    return fetchApi<ResultSet>(this._transactionApiUrl.execute, {
       method: "POST",
       body: JSON.stringify({ uuid, query, params }),
       credentials: "include",
     });
   }
 
+  /**
+   * Commits the transaction identified by the given uuid.
+   *
+   * @param uuid The transaction's uuid
+   */
   async transactionCommit(uuid: string): Promise<null> {
-    return fetchApi<null>(this.transactionApiUrl.commit, {
+    return fetchApi<null>(this._transactionApiUrl.commit, {
       method: "POST",
       body: JSON.stringify({ uuid }),
       credentials: "include",
     });
   }
 
+  /**
+   * Rollbacks the transaction identified by the given uuid.
+   *
+   * @param uuid The transaction's uuid
+   */
   async transactionRollback(uuid: string): Promise<null> {
-    return fetchApi<null>(this.transactionApiUrl.rollback, {
+    return fetchApi<null>(this._transactionApiUrl.rollback, {
       method: "POST",
       body: JSON.stringify({ uuid }),
       credentials: "include",
@@ -100,6 +195,15 @@ export default class Api {
   }
 }
 
+/**
+ * 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
+ */
 const nonNullFetchApi = <R = unknown>(
   input: RequestInfo,
   init?: RequestInit
@@ -123,6 +227,15 @@ const nonNullFetchApi = <R = unknown>(
   );
 };
 
+/**
+ * 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
+ */
 const fetchApi = <R = unknown>(input: RequestInfo, init?: RequestInit) => {
   let headers = init?.headers;
   if (init?.method && init.method !== "GET" && init.method !== "DELETE") {

package/src/api/Client.ts

@@ -1,27 +1,68 @@
-import { Schema } from "../schema/Schema";
+import { Schema } from "../schema/classes/Schema";
 import Api, { RQLParams } from "./Api";
 import Transaction from "./Transaction";
 
+/**
+ * Class used to communicate with a CubicWeb instance's API.
+ */
 export default class Client {
   private api: Api;
 
+  /**
+   * Class used to communicate with a CubicWeb instance's API.
+   *
+   * @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) {
     this.api = new Api(apiUrl);
   }
 
+  get apiUrl() {
+    return this.api.apiUrl;
+  }
+
+  /**
+   * Executes the given query and waits for the response.
+   *
+   * @param query 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 = {}) {
     return await this.api.execute(query, params);
   }
 
+  /**
+   * Retrieves the CubicWeb instance's JSON schema.
+   *
+   * @returns The CubicWeb instance's JSON schema.
+   */
   async schema() {
     const schema = await this.api.schema();
     return new Schema(schema);
   }
 
+  /**
+   * 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
+   * @returns A promise returning true if the login was successful, false otherwise
+   */
   async login(login: string, password: string) {
     return await this.api.login(login, password);
   }
 
+  /**
+   * Creates a new transaction and exposes the Transaction object in the given callback.
+   * Use this callback to execute RQL requests as part of the transaction.
+   * Once the callback's end is reached, the transaction is automatically committed.
+   *
+   * @param callback Function to execute transaction requests in.
+   * @returns The promise returned by the callback
+   */
   async transaction<T>(callback: (tr: Transaction) => Promise<T>): Promise<T> {
     const transaction = new Transaction(this.api);
     await transaction.begin();