kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/service/storage/8/esWrapper.d.ts

@@ -1,19 +1,36 @@
-export = ESWrapper;
+import type { Client } from "sdk-es8";
+import type { JSONObject } from "../../../types/JSONObject";
+import { KuzzleError } from "../../../kerror/errors";
+/**
+ * What the Elasticsearch client throws: an Error, carrying the server's
+ * response on `meta` for the ones that came back from the cluster. `catch`
+ * hands callers `unknown`, and this is the shape every reader below assumes.
+ */
+type ThrownESError = Error & {
+    meta?: JSONObject;
+    body?: JSONObject;
+};
+/**
+ * One that came back from the cluster rather than from the client itself, so
+ * its `meta` is present — which is what `formatESError` checks before handing
+ * it to the handlers below.
+ */
+type ThrownESResponseError = ThrownESError & {
+    meta: JSONObject;
+};
 declare class ESWrapper {
-    constructor(client: any);
-    client: any;
+    client: Client;
+    constructor(client: Client);
     /**
      * Transforms raw ES errors into a normalized Kuzzle version
      *
-     * @param {Error} error
-     * @returns {KuzzleError}
+     * @param error
      */
-    formatESError(error: Error): KuzzleError;
-    reject(error: any): Bluebird<never>;
-    _handleConflictError(error: any, message: any): KuzzleError;
-    _handleNotFoundError(error: any, message: any): KuzzleError;
-    _handleBadRequestError(error: any, message: any): KuzzleError;
-    _handleUnknownError(error: any, message: any): KuzzleError;
+    formatESError(error: unknown): KuzzleError;
+    reject(error: unknown): Promise<never>;
+    _handleConflictError(error: ThrownESResponseError, message: string): KuzzleError;
+    _handleNotFoundError(error: ThrownESResponseError, message: string): KuzzleError;
+    _handleBadRequestError(error: ThrownESResponseError, message: string): KuzzleError;
+    _handleUnknownError(error: ThrownESError, message: string): KuzzleError;
 }
-import { KuzzleError } from "../../../kerror/errors/kuzzleError";
-import Bluebird = require("bluebird");
+export = ESWrapper;

package/dist/lib/service/storage/8/esWrapper.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,18 +19,26 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 /* eslint sort-keys: 0 */
-"use strict";
-const Bluebird = require("bluebird");
-const _ = require("lodash");
-const es = require("sdk-es8");
-const { KuzzleError } = require("../../../kerror/errors");
-const debug = require("../../../util/debug")("kuzzle:services:storage:ESCommon");
-const kerror = require("../../../kerror").wrap("services", "storage");
+const node_util_1 = require("node:util");
+const bluebird_1 = __importDefault(require("bluebird"));
+const get_1 = __importDefault(require("lodash/get"));
+const sdk_es8_1 = require("sdk-es8");
+const errors_1 = require("../../../kerror/errors");
+const debug_1 = __importDefault(require("../../../util/debug"));
+const kerror_1 = require("../../../kerror");
+const debug = (0, debug_1.default)("kuzzle:services:storage:ESCommon");
+const kerror = (0, kerror_1.wrap)("services", "storage");
+function isResponseError(error) {
+    return Boolean(error.meta);
+}
 const errorMessagesMapping = [
     {
         regex: /^\[es_rejected_execution_exception] rejected execution .*? on EsThreadPoolExecutor\[(.*?), .*$/,
-        subCode: "too_many_operations",
+        subcode: "too_many_operations",
         getPlaceholders: (esError, matches) => [matches[1]],
     },
     {
@@ -89,7 +98,7 @@ const errorMessagesMapping = [
     },
     {
         // [index_not_found_exception] no such index, with { resource.type=index_or_alias & resource.id=foso & index=foso }
-        regex: /^no such index \[([%&])(.*)\.(.*)\]$/,
+        regex: /^no such index \[([%&])([^\]]*)\.([^.\]]*)\]$/,
         subcode: "unknown_collection",
         getPlaceholders: (esError, matches) => [matches[2], matches[3]],
     },
@@ -117,14 +126,14 @@ const errorMessagesMapping = [
         getPlaceholders: (esError, matches) => [matches[1]],
     },
     {
-        // mapping set to strict, dynamic introduction of [lehuong] within [_doc] is not allowed
+        // [_doc] mapping set to strict, dynamic introduction of [lehuong] within [_doc] is not allowed
         regex: /^\[(.+)\] mapping set to strict, dynamic introduction of \[(.+)\] within \[.+\] is not allowed/,
         subcode: "strict_mapping_rejection",
         getPlaceholders: (esError, matches) => {
             // "/%26index.collection/_doc"
-            const esPath = esError.meta.meta.request.params.path;
+            const esPath = (0, get_1.default)(esError, "meta.meta.request.params.path", "");
             // keep only "index"
-            const index = esPath.split(".")[0].split("%26")[1];
+            const index = esPath.split(".")[0]?.split("%26")[1];
             // keep only "collection"
             const collection = esPath.substr(esPath.indexOf(".") + 1).split("/")[0];
             return [matches[2], index, collection];
@@ -150,47 +159,58 @@ class ESWrapper {
     /**
      * Transforms raw ES errors into a normalized Kuzzle version
      *
-     * @param {Error} error
-     * @returns {KuzzleError}
+     * @param error
      */
     formatESError(error) {
-        if (error instanceof KuzzleError) {
+        if (error instanceof errors_1.KuzzleError) {
             return error;
         }
+        // `catch` answers `unknown`, and a rejected client promise can in principle
+        // carry anything. Everything below reads an Error's shape, so that is what
+        // it gets — without asserting that whatever arrived already was one.
+        // `inspect`, not `String`: a thrown object stringifies to "[object
+        // Object]", which is the one thing the message must not say.
+        const esError = error instanceof Error ? error : new Error((0, node_util_1.inspect)(error));
         global.kuzzle.emit("services:storage:error", {
-            message: `Elasticsearch Client error: ${error.message}`,
+            message: `Elasticsearch Client error: ${esError.message}`,
             // /!\ not all ES error classes have a "meta" property
-            meta: error.meta || null,
-            stack: error.stack,
+            meta: esError.meta || null,
+            stack: esError.stack,
         });
-        if (error instanceof es.errors.NoLivingConnectionsError) {
+        if (error instanceof sdk_es8_1.errors.NoLivingConnectionsError) {
             throw kerror.get("not_connected");
         }
-        const message = _.get(error, "meta.body.error.reason", error.message);
+        const message = (0, get_1.default)(esError, "meta.body.error.reason", esError.message);
         // Try to match a known elasticsearch error
         for (const betterError of errorMessagesMapping) {
             const matches = message.match(betterError.regex);
             if (matches) {
-                return kerror.get(betterError.subcode, ...betterError.getPlaceholders(error, matches));
+                return kerror.get(betterError.subcode, ...betterError.getPlaceholders(esError, matches));
             }
         }
         // Try to match using error codes
-        if (error.meta) {
-            switch (error.meta.statusCode) {
+        // `meta` is what tells a cluster response from a client-side failure, so
+        // the three handlers below are declared to require it rather than
+        // re-checking it four times each. The error itself is handed over, never a
+        // copy: the client's `ResponseError` exposes `body` as a prototype getter,
+        // which a spread does not carry — and without it every missing document
+        // answered `unexpected_not_found` instead of `not_found`.
+        if (isResponseError(esError)) {
+            switch (esError.meta.statusCode) {
                 case 400:
-                    return this._handleBadRequestError(error, message);
+                    return this._handleBadRequestError(esError, message);
                 case 404:
-                    return this._handleNotFoundError(error, message);
+                    return this._handleNotFoundError(esError, message);
                 case 409:
-                    return this._handleConflictError(error, message);
+                    return this._handleConflictError(esError, message);
                 default:
                     break;
             }
         }
-        return this._handleUnknownError(error, message);
+        return this._handleUnknownError(esError, message);
     }
     reject(error) {
-        return Bluebird.reject(this.formatESError(error));
+        return bluebird_1.default.reject(this.formatESError(error));
     }
     _handleConflictError(error, message) {
         debug('unhandled "Conflict" elasticsearch error: %a', error);
@@ -198,46 +218,47 @@ class ESWrapper {
     }
     _handleNotFoundError(error, message) {
         let errorMessage = message;
-        if (!error.body._index) {
+        const indice = (0, get_1.default)(error, "body._index");
+        if (!indice) {
             return kerror.get("unexpected_not_found", errorMessage);
         }
         // _index= "&nyc-open-data.yellow-taxi"
-        const index = error.body._index.split(".")[0].slice(1);
-        const collection = error.body._index.split(".")[1];
+        const index = indice.split(".")[0]?.slice(1);
+        const collection = indice.split(".")[1];
         // 404 on a GET document
-        if (error.body.found === false) {
+        if (error.body?.found === false) {
             return kerror.get("not_found", error.body._id, index, collection);
         }
         // 404 on DELETE document (ES error payloads are so cool!)
         if (error.meta.body._id) {
             return kerror.get("not_found", error.meta.body._id, index, collection);
         }
-        if (error.meta.body && error.meta.body.error) {
+        if (error.meta.body?.error) {
             errorMessage = error.meta.body.error
                 ? `${error.meta.body.error.reason}: ${error.meta.body.error["resource.id"]}`
-                : `${error.message}: ${error.body._id}`;
+                : `${error.message}: ${error.body?._id}`;
         }
         debug('unhandled "NotFound" elasticsearch error: %a', error);
         return kerror.get("unexpected_not_found", errorMessage);
     }
     _handleBadRequestError(error, message) {
         let errorMessage = message;
-        if (error.meta.body && error.meta.body.error) {
+        if (error.meta.body?.error) {
             errorMessage = error.meta.body.error.root_cause
                 ? error.meta.body.error.root_cause[0].reason
                 : error.meta.body.error.reason;
             // empty query throws exception with ES 7
             if (error.meta.body.error.type === "parsing_exception" &&
-                _.get(error, "meta.body.error.caused_by.type") ===
+                (0, get_1.default)(error, "meta.body.error.caused_by.type") ===
                     "illegal_argument_exception") {
                 errorMessage = error.meta.body.error.caused_by.reason;
             }
         }
-        debug('unhandled "BadRequest" elasticsearch error: %a', _.get(error, "meta.body.error.reason", error.message));
+        debug('unhandled "BadRequest" elasticsearch error: %a', (0, get_1.default)(error, "meta.body.error.reason", error.message));
         return kerror.get("unexpected_bad_request", errorMessage);
     }
     _handleUnknownError(error, message) {
-        debug("unhandled elasticsearch error (unhandled type: %s): %o", _.get(error, "error.meta.statusCode", "<no status code>"), error);
+        debug("unhandled elasticsearch error (unhandled type: %s): %o", (0, get_1.default)(error, "error.meta.statusCode", "<no status code>"), error);
         return kerror.get("unexpected_error", message);
     }
 }

package/dist/lib/service/storage/commons/queryTranslator.d.ts

@@ -1,5 +1,5 @@
 export declare class QueryTranslator {
-    translate(filters: any): any;
-    _translateOperator(operator: any, operands: any): any;
-    _translateClause(clause: any, content: any): any;
+    translate(filters: unknown): any;
+    _translateOperator(operator: unknown, operands: unknown): any;
+    _translateClause(clause: unknown, content: unknown): any;
 }

package/dist/lib/service/storage/commons/queryTranslator.js

@@ -1,27 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryTranslator = void 0;
-/*
- * Kuzzle, a backend software, self-hostable and ready to use
- * to power modern apps
- *
- * Copyright 2015-2022 Kuzzle
- * mailto: support AT kuzzle.io
- * website: http://kuzzle.io
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * https://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
 const kerror_1 = require("../../../kerror");
+const safeObject_1 = require("../../../util/safeObject");
+/**
+ * The payload of a clause that is the same Elasticsearch query under another
+ * name, and so is spread into it verbatim. Only `exists` and `missing` accept
+ * the string form.
+ */
+function asClauseObject(content) {
+    if (!(0, safeObject_1.isPlainObject)(content)) {
+        throw (0, kerror_1.get)("services", "koncorde", "elastic_translation_error", `Invalid clause payload: expected an object, got ${typeof content}`);
+    }
+    return content;
+}
+/**
+ * A Koncorde filter, as `translate` recurses over it: one keyword and its
+ * payload. Anything else is a malformed filter, and the translation error
+ * this module already raises for a malformed `exists` path says so.
+ */
+function asFilter(value) {
+    if (!(0, safeObject_1.isPlainObject)(value)) {
+        throw (0, kerror_1.get)("services", "koncorde", "elastic_translation_error", `Invalid operand: expected a filter object, got ${typeof value}`);
+    }
+    return value;
+}
+function asFilterList(value) {
+    if (!Array.isArray(value)) {
+        throw (0, kerror_1.get)("services", "koncorde", "elastic_translation_error", `Invalid operands: expected a list of filters, got ${typeof value}`);
+    }
+    return value.map(asFilter);
+}
 class KeywordError extends Error {
     constructor(type, name) {
         super(`The ${type} "${name}" of Koncorde DSL is not supported for search queries.`);
@@ -55,12 +64,16 @@ function parseKoncordePath(path) {
 const KONCORDE_CLAUSES_TO_ES = {
     equals: (content) => ({
         term: {
-            ...content,
+            ...asClauseObject(content),
         },
     }),
     exists: (field) => {
         // Support old syntax { exists: { field: "path" } } and { exists: "path" }
-        const parsedInfo = parseKoncordePath(field.field || field);
+        const declared = (0, safeObject_1.isPlainObject)(field) ? field.field : field;
+        if (typeof declared !== "string") {
+            throw (0, kerror_1.get)("services", "koncorde", "elastic_translation_error", `Invalid exists path: expected a string, got ${typeof declared}`);
+        }
+        const parsedInfo = parseKoncordePath(declared);
         // If we have a value, we need to use a range query to be sure that the value is the same
         if (parsedInfo.value) {
             return {
@@ -91,32 +104,32 @@ const KONCORDE_CLAUSES_TO_ES = {
     },
     geoBoundingBox: (content) => ({
         geo_bounding_box: {
-            ...content,
+            ...asClauseObject(content),
         },
     }),
     geoDistance: (content) => ({
         geo_distance: {
-            ...content,
+            ...asClauseObject(content),
         },
     }),
     geoDistanceRange: (content) => ({
         geo_distance_range: {
-            ...content,
+            ...asClauseObject(content),
         },
     }),
     geoPolygon: (content) => ({
         geo_polygon: {
-            ...content,
+            ...asClauseObject(content),
         },
     }),
     ids: (content) => ({
         ids: {
-            ...content,
+            ...asClauseObject(content),
         },
     }),
     in: (content) => ({
         terms: {
-            ...content,
+            ...asClauseObject(content),
         },
     }),
     missing: (field) => ({
@@ -126,19 +139,26 @@ const KONCORDE_CLAUSES_TO_ES = {
     }),
     range: (content) => ({
         range: {
-            ...content,
+            ...asClauseObject(content),
         },
     }),
 };
 const KONCORDE_OPERATORS_TO_ES = {
     and: (content) => ({
         bool: {
-            filter: [...content],
+            filter: [...asFilterList(content)],
         },
     }),
     bool: undefined,
     not: (content) => {
-        const [name, value] = Object.entries(content[0])[0];
+        // `not` is handed the single already-translated filter below, so its
+        // first entry is the ES clause to negate.
+        const [first] = asFilterList(content);
+        const [entry] = Object.entries(asFilter(first));
+        if (entry === undefined) {
+            throw (0, kerror_1.get)("services", "koncorde", "elastic_translation_error", "Invalid not operand: the negated filter is empty");
+        }
+        const [name, value] = entry;
         return {
             bool: {
                 must_not: [{ [name]: value }],
@@ -147,13 +167,26 @@ const KONCORDE_OPERATORS_TO_ES = {
     },
     or: (content) => ({
         bool: {
-            should: [...content],
+            should: [...asFilterList(content)],
         },
     }),
 };
+/*
+ * The three public methods below keep v2.56.0's declarations — untyped
+ * arguments, an `any` answer — as a public overload in front of the typed
+ * implementation: a `JSONObject` answer breaks code compiled against that
+ * which assigns it to its own query type.
+ */
 class QueryTranslator {
     translate(filters) {
-        const [name, value] = Object.entries(filters)[0];
+        const [entry] = Object.entries(filters);
+        // An empty filter has no keyword to translate. `BaseController`'s
+        // `translateKoncorde` answers `{}` before reaching here; this is what
+        // destructuring `Object.entries(filters)[0]` raised a TypeError for.
+        if (entry === undefined) {
+            throw (0, kerror_1.get)("services", "koncorde", "elastic_translation_error", "Invalid filter: no keyword to translate");
+        }
+        const [name, value] = entry;
         if (KONCORDE_OPERATORS.includes(name)) {
             return this._translateOperator(name, value);
         }
@@ -166,10 +199,10 @@ class QueryTranslator {
         }
         const esOperands = [];
         if (operator === "not") {
-            esOperands.push(this.translate(operands));
+            esOperands.push(this.translate(asFilter(operands)));
         }
         else {
-            for (const operand of operands) {
+            for (const operand of asFilterList(operands)) {
                 esOperands.push(this.translate(operand));
             }
         }
@@ -182,6 +215,9 @@ class QueryTranslator {
                 [clause]: content,
             };
         }
+        if (!(0, safeObject_1.isPlainObject)(content) && typeof content !== "string") {
+            throw (0, kerror_1.get)("services", "koncorde", "elastic_translation_error", `Invalid "${clause}" clause: expected an object or a string, got ${typeof content}`);
+        }
         return converter(content);
     }
 }

package/dist/lib/types/ApiRoute.d.ts

@@ -0,0 +1,12 @@
+import type { JSONObject } from "./JSONObject";
+/**
+ * One entry of the HTTP route table the API exposes, native or plugin-provided.
+ */
+export interface ApiRoute {
+    controller: string;
+    action: string;
+    path: string;
+    verb: string;
+    /** Attached by `PluginsManager` for a plugin route that declares one. */
+    openapi?: JSONObject;
+}

package/dist/lib/types/ApiRoute.js

@@ -0,0 +1,23 @@
+"use strict";
+/*
+ * Kuzzle, a backend software, self-hostable and ready to use
+ * to power modern apps
+ *
+ * Copyright 2015-2022 Kuzzle
+ * mailto: support AT kuzzle.io
+ * website: http://kuzzle.io
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ApiRoute.js.map

package/dist/lib/types/ClientConnection.d.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from "kuzzle-sdk";
+import type { JSONObject } from "./JSONObject";
 export interface ClientConnection {
     id: string;
     protocol: string;

package/dist/lib/types/EventHandler.d.ts

@@ -44,6 +44,16 @@ export type HookEventHandler<TEventDefinition extends EventDefinition = EventDef
  * It should return a promise resolving the first received argument.
  */
 export type PipeEventHandler<TEventDefinition extends EventDefinition = EventDefinition> = (...args: TEventDefinition["args"]) => Promise<TEventDefinition["args"][0]>;
+/**
+ * A plugin pipe in its **callback** form: instead of answering a promise it
+ * takes a trailing `callback(error, result)`. The pipe runner supports both,
+ * and `PluginsManager.registerPipe` always hands over this one.
+ */
+export type CallbackPipeHandler = (...args: unknown[]) => void;
+/**
+ * What the emitter actually stores for a plugin pipe: either form.
+ */
+export type RegisteredPipeHandler<TEventDefinition extends EventDefinition = EventDefinition> = PipeEventHandler<TEventDefinition> | CallbackPipeHandler;
 /**
  * Handler for cluster event.
  */

package/dist/lib/types/Global.d.ts

@@ -1,5 +1,5 @@
-import { Backend } from "../core/backend";
-import { Kuzzle } from "../kuzzle";
+import type { Backend } from "../core/backend";
+import type { Kuzzle } from "../kuzzle";
 /**
  * This file contains global type declarations for Kuzzle.
  * We need to use `var` so Typescript extends the globalThis type.
@@ -8,6 +8,11 @@ import { Kuzzle } from "../kuzzle";
 declare global {
     var app: Backend;
     var kuzzle: Kuzzle;
-    var NODE_ENV: string;
+    var nodeId: string;
+    /**
+     * `process.env.NODE_ENV`, which is not guaranteed to be set — every reader
+     * compares it against a literal, so the absent case was already handled.
+     */
+    var NODE_ENV: string | undefined;
 }
 export {};

package/dist/lib/types/HttpMessage.d.ts

@@ -1,5 +1,5 @@
-import { JSONObject } from "kuzzle-sdk";
-import { ClientConnection } from "./ClientConnection";
+import type { JSONObject } from "./JSONObject";
+import type { ClientConnection } from "./ClientConnection";
 export interface HttpMessage {
     connection: ClientConnection;
     content: JSONObject;

package/dist/lib/types/HttpStream.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-import { Readable } from "stream";
+import type { Readable } from "stream";
 export type HttpStreamProperties = {
     totalBytes?: number;
 };

package/dist/lib/types/HttpStream.js

@@ -27,7 +27,9 @@ exports.HttpStream = void 0;
  */
 class HttpStream {
     get readableState() {
-        // @ts-ignore
+        // @ts-expect-error -- `_readableState` is Node's internal bookkeeping and
+        // is not declared by @types/node; it is where a destroyed stream's error
+        // lands, and `errored` is the only field read from it.
         return this.stream._readableState;
     }
     constructor(readableStream, { totalBytes = -1 } = {}) {

package/dist/lib/types/JSONObject.d.ts

@@ -0,0 +1,9 @@
+/**
+ * An object with any key and any value — a JSON document, a request body, a
+ * payload.
+ *
+ * Kuzzle's own definition (ADR-0002 step 02), declared exactly as kuzzle-sdk
+ * declares its `JSONObject`, so that a value of one is a value of the other,
+ * both ways: a plugin mixing the two imports sees no difference.
+ */
+export type JSONObject = Record<PropertyKey, any>;

package/dist/lib/types/JSONObject.js

@@ -0,0 +1,23 @@
+"use strict";
+/*
+ * Kuzzle, a backend software, self-hostable and ready to use
+ * to power modern apps
+ *
+ * Copyright 2015-2022 Kuzzle
+ * mailto: support AT kuzzle.io
+ * website: http://kuzzle.io
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=JSONObject.js.map

package/dist/lib/types/Kuzzle.d.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from "kuzzle-sdk";
+import type { JSONObject } from "./JSONObject";
 export type InstallationConfig = {
     id: string;
     handler: () => Promise<void>;
@@ -7,9 +7,11 @@ export type InstallationConfig = {
 export type StartOptions = {
     import?: JSONObject;
     plugins?: JSONObject;
-    secretsFile?: JSONObject;
+    /** Path to the encrypted secrets file — see `lib/kuzzle/vault.ts`. */
+    secretsFile?: string;
     support?: JSONObject;
-    vaultKey?: JSONObject;
+    /** Key the encrypted secrets file is decrypted with. */
+    vaultKey?: string;
     installations?: Array<InstallationConfig>;
 };
 export type ImportConfig = {

package/dist/lib/types/KuzzleDocument.d.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from "kuzzle-sdk";
+import type { JSONObject } from "./JSONObject";
 /**
  * @deprecated Use KDocument instead (See https://docs.kuzzle.io/sdk/js/7/essentials/strong-typing/)
  */

package/dist/lib/types/KuzzleWebSocket.d.ts

@@ -0,0 +1,24 @@
+import type { JSONObject } from "./JSONObject";
+import type uWS from "uWebSockets.js";
+/**
+ * What Kuzzle hands `res.upgrade()` as the socket's user data.
+ *
+ * uWebSockets merges it onto the socket object itself, which is why the code
+ * reads `socket.internal` rather than `socket.getUserData().internal` — the
+ * intersection below is what says so.
+ */
+export interface KuzzleSocketData {
+    headers: JSONObject;
+    internal: {
+        debugSession?: boolean;
+    };
+    /**
+     * Rate-limiting bookkeeping. Seeded by `wsOnUpgradeHandler` along with the
+     * rest of this data, so the limiter can read `count` in the branch that did
+     * not just write it — which is what it always did.
+     */
+    last: number;
+    count: number;
+}
+/** A WebSocket carrying Kuzzle's own upgrade data. */
+export type KuzzleWebSocket = uWS.WebSocket<unknown> & KuzzleSocketData;