From 731b99fd196e01991daf73cd186f98e65e787899 Mon Sep 17 00:00:00 2001 From: Adrien Maret Date: Mon, 7 Dec 2020 11:12:30 +0100 Subject: [PATCH] Rename KuzzleRequest to RequestPayload (#565) Rename KuzzleRequest and KuzzleResponse to RequestPayload and ResponsePayload Also move type definitions to types/ Those types are exactly the same as in Kuzzle. --- .eslintignore | 2 +- .gitignore | 2 +- index.ts | 2 +- package-lock.json | 2 +- package.json | 2 +- src/Kuzzle.ts | 8 +- src/KuzzleError.ts | 4 + src/controllers/Auth.ts | 2 +- src/controllers/Base.ts | 5 +- src/controllers/Collection.ts | 2 +- src/controllers/Document.ts | 2 +- src/controllers/Realtime.ts | 2 +- src/core/searchResult/Document.ts | 2 +- src/core/searchResult/SearchResultBase.ts | 7 +- src/core/searchResult/Specifications.ts | 2 +- src/core/security/Profile.ts | 2 +- src/core/security/Role.ts | 2 +- src/core/security/User.ts | 2 +- src/protocols/Http.ts | 5 +- src/protocols/WebSocket.ts | 5 +- src/protocols/abstract/Base.ts | 5 +- src/types/ApiKey.ts | 34 ++ src/types/Document.ts | 72 ++++ src/types/HttpRoutes.ts | 36 ++ src/types/JSONObject.ts | 6 + src/types/Mappings.ts | 42 ++ src/types/Notification.ts | 102 +++++ src/types/ProfilePolicy.ts | 40 ++ src/types/RequestPayload.ts | 55 +++ src/types/ResponsePayload.ts | 88 +++++ src/types/RoleRightsDefinition.ts | 36 ++ src/types/index.ts | 15 + src/utils/interfaces.ts | 442 ---------------------- 33 files changed, 565 insertions(+), 470 deletions(-) create mode 100644 src/types/ApiKey.ts create mode 100644 src/types/Document.ts create mode 100644 src/types/HttpRoutes.ts create mode 100644 src/types/JSONObject.ts create mode 100644 src/types/Mappings.ts create mode 100644 src/types/Notification.ts create mode 100644 src/types/ProfilePolicy.ts create mode 100644 src/types/RequestPayload.ts create mode 100644 src/types/ResponsePayload.ts create mode 100644 src/types/RoleRightsDefinition.ts create mode 100644 src/types/index.ts delete mode 100644 src/utils/interfaces.ts diff --git a/.eslintignore b/.eslintignore index 91cef1057..855255188 100644 --- a/.eslintignore +++ b/.eslintignore @@ -18,7 +18,7 @@ src/protocols/abstract/Realtime.js src/protocols/Http.js src/protocols/WebSocket.js src/protocols/index.js -src/utils/interfaces.js +src/types/*.js src/core/KuzzleEventEmitter.js src/core/searchResult/SearchResultBase.js src/core/searchResult/Document.js diff --git a/.gitignore b/.gitignore index 1f5aa706a..2497aacb9 100644 --- a/.gitignore +++ b/.gitignore @@ -46,7 +46,7 @@ src/protocols/abstract/Realtime.js src/protocols/Http.js src/protocols/WebSocket.js src/protocols/index.js -src/utils/interfaces.js +src/types/*.js src/core/KuzzleEventEmitter.js src/core/searchResult/SearchResultBase.js src/core/searchResult/Document.js diff --git a/index.ts b/index.ts index 633ecbe28..746f37af9 100644 --- a/index.ts +++ b/index.ts @@ -20,7 +20,7 @@ export * from './src/core/searchResult/Role'; export * from './src/core/searchResult/Specifications'; export * from './src/core/searchResult/User'; -export * from './src/utils/interfaces'; +export * from './src/types'; export * from './src/controllers/Auth'; export * from './src/controllers/Base'; diff --git a/package-lock.json b/package-lock.json index 7876235fb..fb91f36d8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "kuzzle-sdk", - "version": "7.4.3", + "version": "7.4.4", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index fa6560d01..efb51250c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "kuzzle-sdk", - "version": "7.4.3", + "version": "7.4.4", "description": "Official Javascript SDK for Kuzzle", "author": "The Kuzzle Team ", "repository": { diff --git a/src/Kuzzle.ts b/src/Kuzzle.ts index b19d4ed90..a561e1e99 100644 --- a/src/Kuzzle.ts +++ b/src/Kuzzle.ts @@ -13,7 +13,9 @@ import { MemoryStorageController } from './controllers/MemoryStorage'; import { uuidv4 } from './utils/uuidv4'; import { proxify } from './utils/proxify'; -import { JSONObject, KuzzleRequest, KuzzleResponse } from './utils/interfaces'; +import { JSONObject } from './types'; +import { RequestPayload } from './types/RequestPayload'; +import { ResponsePayload } from './types/ResponsePayload'; // Defined by webpack plugin declare const SDKVERSION: any; @@ -132,7 +134,7 @@ export class Kuzzle extends KuzzleEventEmitter { * Custom function called during offline mode to filter * queued requests on-the-fly */ - queueFilter?: (request: KuzzleRequest) => boolean; + queueFilter?: (request: RequestPayload) => boolean; /** * Called before dequeuing requests after exiting offline mode, * to add items at the beginning of the offline queue @@ -524,7 +526,7 @@ export class Kuzzle extends KuzzleEventEmitter { * @param request * @param options - Optional arguments */ - query (request: KuzzleRequest = {}, options: JSONObject = {}): Promise { + query (request: RequestPayload = {}, options: JSONObject = {}): Promise { if (typeof request !== 'object' || Array.isArray(request)) { throw new Error(`Kuzzle.query: Invalid request: ${JSON.stringify(request)}`); } diff --git a/src/KuzzleError.ts b/src/KuzzleError.ts index 659367274..faa638781 100644 --- a/src/KuzzleError.ts +++ b/src/KuzzleError.ts @@ -48,6 +48,10 @@ export class KuzzleError extends Error { }); } + if (stack) { + this.stack = stack; + } + this.id = apiError.id; this.code = apiError.code; diff --git a/src/controllers/Auth.ts b/src/controllers/Auth.ts index 9ed867c18..0a388ba2b 100644 --- a/src/controllers/Auth.ts +++ b/src/controllers/Auth.ts @@ -1,7 +1,7 @@ import { Jwt } from '../core/Jwt'; import { BaseController } from './Base'; import { User } from '../core/security/User'; -import { JSONObject, ApiKey } from '../utils/interfaces'; +import { JSONObject, ApiKey } from '../types'; /** * Auth controller diff --git a/src/controllers/Base.ts b/src/controllers/Base.ts index 8115fc82a..62e6f8d41 100644 --- a/src/controllers/Base.ts +++ b/src/controllers/Base.ts @@ -1,4 +1,5 @@ -import { KuzzleRequest, JSONObject } from '../utils/interfaces'; +import { JSONObject } from '../types'; +import { RequestPayload } from '../types/RequestPayload'; export class BaseController { private _name: string; @@ -34,7 +35,7 @@ export class BaseController { * @param request * @param options */ - query (request: KuzzleRequest = {}, options: any = {}): Promise { + query (request: RequestPayload = {}, options: any = {}): Promise { request.controller = request.controller || this.name; return this._kuzzle.query(request, options); diff --git a/src/controllers/Collection.ts b/src/controllers/Collection.ts index 522db6a4d..f58968124 100644 --- a/src/controllers/Collection.ts +++ b/src/controllers/Collection.ts @@ -1,6 +1,6 @@ import { BaseController } from './Base'; import { SpecificationsSearchResult } from '../core/searchResult/Specifications'; -import { CollectionMappings, JSONObject } from '../utils/interfaces'; +import { CollectionMappings, JSONObject } from '../types'; export class CollectionController extends BaseController { constructor (kuzzle) { diff --git a/src/controllers/Document.ts b/src/controllers/Document.ts index 60a3c77fc..6faaf425c 100644 --- a/src/controllers/Document.ts +++ b/src/controllers/Document.ts @@ -1,7 +1,7 @@ import { BaseController } from './Base'; import { SearchResult } from '../core/searchResult/SearchResultBase'; import { DocumentSearchResult } from '../core/searchResult/Document'; -import { JSONObject, Document, DocumentHit } from '../utils/interfaces'; +import { JSONObject, Document, DocumentHit } from '../types'; export class DocumentController extends BaseController { constructor (kuzzle) { diff --git a/src/controllers/Realtime.ts b/src/controllers/Realtime.ts index 602f499e8..cf3d0d4e5 100644 --- a/src/controllers/Realtime.ts +++ b/src/controllers/Realtime.ts @@ -1,6 +1,6 @@ import { BaseController } from './Base'; import Room from '../core/Room'; -import { Notification, JSONObject } from '../utils/interfaces'; +import { Notification, JSONObject } from '../types'; /** * Enum for `scope` option of realtime.subscribe method diff --git a/src/core/searchResult/Document.ts b/src/core/searchResult/Document.ts index de992df3d..5dfe290b1 100644 --- a/src/core/searchResult/Document.ts +++ b/src/core/searchResult/Document.ts @@ -1,5 +1,5 @@ import { SearchResultBase } from './SearchResultBase'; -import { DocumentHit } from '../../utils/interfaces'; +import { DocumentHit } from '../../types'; export class DocumentSearchResult extends SearchResultBase { /** diff --git a/src/core/searchResult/SearchResultBase.ts b/src/core/searchResult/SearchResultBase.ts index c48ea9c71..96ba70fe0 100644 --- a/src/core/searchResult/SearchResultBase.ts +++ b/src/core/searchResult/SearchResultBase.ts @@ -1,4 +1,5 @@ -import { JSONObject, KuzzleRequest } from '../../utils/interfaces'; +import { JSONObject } from '../../types'; +import { RequestPayload } from '../../types/RequestPayload'; import { Kuzzle } from '../../Kuzzle'; export interface SearchResult { @@ -42,7 +43,7 @@ export class SearchResultBase implements SearchResult { protected _searchAction: string; protected _scrollAction: string; protected _controller: string; - protected _request: KuzzleRequest; + protected _request: RequestPayload; protected _kuzzle: Kuzzle; protected _options: JSONObject; protected _response: JSONObject; @@ -57,7 +58,7 @@ export class SearchResultBase implements SearchResult { constructor ( kuzzle: Kuzzle, - request: KuzzleRequest = {}, + request: RequestPayload = {}, options: JSONObject = {}, response: any = {} ) { diff --git a/src/core/searchResult/Specifications.ts b/src/core/searchResult/Specifications.ts index 54b21df0f..a42d93162 100644 --- a/src/core/searchResult/Specifications.ts +++ b/src/core/searchResult/Specifications.ts @@ -1,5 +1,5 @@ import { SearchResultBase } from './SearchResultBase'; -import { JSONObject } from '../../utils/interfaces'; +import { JSONObject } from '../../types'; export class SpecificationsSearchResult extends SearchResultBase { diff --git a/src/core/security/Profile.ts b/src/core/security/Profile.ts index 044844635..7781b75b4 100644 --- a/src/core/security/Profile.ts +++ b/src/core/security/Profile.ts @@ -1,5 +1,5 @@ import { Role } from './Role'; -import { ProfilePolicy } from '../../utils/interfaces'; +import { ProfilePolicy } from '../../types'; export class Profile { /** diff --git a/src/core/security/Role.ts b/src/core/security/Role.ts index 5e2d4bbca..0f3d0592a 100644 --- a/src/core/security/Role.ts +++ b/src/core/security/Role.ts @@ -1,4 +1,4 @@ -import { RoleRightsDefinition } from '../../utils/interfaces'; +import { RoleRightsDefinition } from '../../types'; export class Role { /** diff --git a/src/core/security/User.ts b/src/core/security/User.ts index 1e54da94c..82db5728d 100644 --- a/src/core/security/User.ts +++ b/src/core/security/User.ts @@ -1,4 +1,4 @@ -import { JSONObject } from '../../utils/interfaces'; +import { JSONObject } from '../../types'; import { Profile } from './Profile'; export class User { diff --git a/src/protocols/Http.ts b/src/protocols/Http.ts index 8525c9bfa..7a50f90ea 100644 --- a/src/protocols/Http.ts +++ b/src/protocols/Http.ts @@ -2,7 +2,8 @@ import staticHttpRoutes from './routes.json'; import { KuzzleAbstractProtocol } from './abstract/Base'; -import { HttpRoutes, JSONObject, KuzzleRequest } from '../utils/interfaces'; +import { HttpRoutes, JSONObject } from '../types'; +import { RequestPayload } from '../types/RequestPayload'; /** * Http protocol used to connect to a Kuzzle server. @@ -177,7 +178,7 @@ export default class HttpProtocol extends KuzzleAbstractProtocol { * @param {Object} data * @returns {Promise} */ - send (request: KuzzleRequest, options: JSONObject = {}) { + send (request: RequestPayload, options: JSONObject = {}) { const route = this.routes[request.controller] && this.routes[request.controller][request.action]; diff --git a/src/protocols/WebSocket.ts b/src/protocols/WebSocket.ts index 6d28f51a8..fbc071223 100644 --- a/src/protocols/WebSocket.ts +++ b/src/protocols/WebSocket.ts @@ -2,7 +2,8 @@ import { KuzzleError } from '../KuzzleError'; import { BaseProtocolRealtime } from './abstract/Realtime'; -import { JSONObject, KuzzleRequest } from '../utils/interfaces'; +import { JSONObject } from '../types'; +import { RequestPayload } from '../types/RequestPayload'; /** * WebSocket protocol used to connect to a Kuzzle server. @@ -157,7 +158,7 @@ export default class WebSocketProtocol extends BaseProtocolRealtime { * * @param {Object} payload */ - send (request: KuzzleRequest) { + send (request: RequestPayload) { if (this.client && this.client.readyState === this.client.OPEN) { this.client.send(JSON.stringify(request)); } diff --git a/src/protocols/abstract/Base.ts b/src/protocols/abstract/Base.ts index 67dccd9ad..e028ddd46 100644 --- a/src/protocols/abstract/Base.ts +++ b/src/protocols/abstract/Base.ts @@ -4,7 +4,8 @@ import { KuzzleError } from '../../KuzzleError'; import { uuidv4 } from '../../utils/uuidv4'; import { KuzzleEventEmitter } from '../../core/KuzzleEventEmitter'; import { PendingRequest } from './PendingRequest'; -import { KuzzleRequest, JSONObject } from '../../utils/interfaces'; +import { JSONObject } from '../../types'; +import { RequestPayload } from '../../types/RequestPayload'; export abstract class KuzzleAbstractProtocol extends KuzzleEventEmitter { private _pendingRequests: Map; @@ -96,7 +97,7 @@ export abstract class KuzzleAbstractProtocol extends KuzzleEventEmitter { abstract connect (): Promise - abstract send (request: KuzzleRequest, options: JSONObject): void + abstract send (request: RequestPayload, options: JSONObject): void /** * Called when the client's connection is established diff --git a/src/types/ApiKey.ts b/src/types/ApiKey.ts new file mode 100644 index 000000000..dd4dd8563 --- /dev/null +++ b/src/types/ApiKey.ts @@ -0,0 +1,34 @@ +/** + * ApiKey + */ +export type ApiKey = { + /** + * ApiKey unique ID + */ + _id: string; + /** + * ApiKey content + */ + _source: { + /** + * User kuid + */ + userId: string; + /** + * Expiration date in Epoch-millis format (-1 if the token never expires) + */ + expiresAt: number; + /** + * Original TTL in ms + */ + ttl: number; + /** + * API key description + */ + description: string; + /** + * Authentication token associated with this API key + */ + token: string; + } +} diff --git a/src/types/Document.ts b/src/types/Document.ts new file mode 100644 index 000000000..ddd29b755 --- /dev/null +++ b/src/types/Document.ts @@ -0,0 +1,72 @@ +import { JSONObject } from './JSONObject'; + +/** + * Kuzzle metadata + * @see https://docs.kuzzle.io/core/2/guides/essentials/document-metadata/ + */ +export interface DocumentMetadata { + _kuzzle_info: { + /** + * Kuid of the user who created the document + */ + author: string, + /** + * Creation date in micro-timestamp + */ + createdAt: number, + /** + * Kuid of the user who last updated the document + */ + updater: string | null, + /** + * Update date in micro-timestamp + */ + updatedAt: number | null + } +} + +/** + * Represents the `_source` property of the document + */ +export interface DocumentContent extends DocumentMetadata { + [key: string]: JSONObject | any, +} + +/** + * Kuzzle document + * + * @property _id + * @property _version + * @property _source + */ +export class Document { + /** + * Document unique ID + */ + _id: string; + /** + * Document Version (generated by Elasticsearch) + */ + _version?: number; + /** + * Document Content + */ + _source: DocumentContent; + + [key: string]: JSONObject | any; +} + +/** + * Document retrieved from a search + * + * @property _id + * @property _version + * @property _source + * @property _score + */ +export interface DocumentHit extends Document { + /** + * Relevance score + */ + _score: number; +} \ No newline at end of file diff --git a/src/types/HttpRoutes.ts b/src/types/HttpRoutes.ts new file mode 100644 index 000000000..4fac08e20 --- /dev/null +++ b/src/types/HttpRoutes.ts @@ -0,0 +1,36 @@ +/** + * HTTP routes definition format + * @example + * { + * : { + * : { verb: , url: } + * } + * } + * + * { + * 'my-plugin/my-controller': { + * action: { verb: 'GET', url: '/some/url' }, + * action2: { verb: 'GET', url: '/some/url/with/:parameter' } + * } + * } + */ +export type HttpRoutes = { + /** + * Controller name + */ + [controller: string]: { + /** + * Action name + */ + [action: string]: { + /** + * HTTP verb + */ + verb: string, + /** + * URL + */ + url: string + } + } +} diff --git a/src/types/JSONObject.ts b/src/types/JSONObject.ts new file mode 100644 index 000000000..5ac0a5833 --- /dev/null +++ b/src/types/JSONObject.ts @@ -0,0 +1,6 @@ +/** + * An interface representing an object with string key and any value + */ +export interface JSONObject { + [key: string]: JSONObject | any +} diff --git a/src/types/Mappings.ts b/src/types/Mappings.ts new file mode 100644 index 000000000..8d9472fec --- /dev/null +++ b/src/types/Mappings.ts @@ -0,0 +1,42 @@ +import { JSONObject } from './JSONObject'; + +export type MappingsProperties = { + /** + * Properties types definition + * + * @see https://docs.kuzzle.io/core/2/guides/essentials/database-mappings/#properties-types-definition + */ + properties?: MappingsProperties, + /** + * Dynamic mapping policy + * + * @see https://docs.kuzzle.io/core/2/guides/essentials/database-mappings/#dynamic-mapping-policy + */ + dynamic?: 'true' | 'false' | 'strict' +} + +/** + * Collection mappings definition + * + * @see https://docs.kuzzle.io/core/2/guides/essentials/database-mappings/ + */ +export type CollectionMappings = { + /** + * Collection metadata + * + * @see https://docs.kuzzle.io/core/2/guides/essentials/database-mappings/#collection-metadata + */ + _meta?: JSONObject; + /** + * Properties types definition + * + * @see https://docs.kuzzle.io/core/2/guides/essentials/database-mappings/#properties-types-definition + */ + properties?: MappingsProperties, + /** + * Dynamic mapping policy + * + * @see https://docs.kuzzle.io/core/2/guides/essentials/database-mappings/#dynamic-mapping-policy + */ + dynamic?: 'true' | 'false' | 'strict', +} diff --git a/src/types/Notification.ts b/src/types/Notification.ts new file mode 100644 index 000000000..1e64c172e --- /dev/null +++ b/src/types/Notification.ts @@ -0,0 +1,102 @@ +import { JSONObject } from './JSONObject'; + +/** + * Enum for notification types + */ +export type NotificationType = 'document' | 'user' | 'TokenExpired' + +/** + * Real-time notifications sent by Kuzzle. + * + */ +export interface Notification { + /** + * Notification type + */ + type: NotificationType; +} + +export interface BaseNotification extends Notification { + /** + * Controller that triggered the notification + */ + controller: string; + /** + * Action that triggered the notification + */ + action: string; + /** + * Index name + */ + index: string; + /** + * Collection name + */ + collection: string; + /** + * Network protocol used to trigger the notification + */ + protocol: string; + /** + * Subscription channel identifier. + * Can be used to link a notification to its corresponding subscription + */ + room: string; + /** + * Timestamp of the event, in Epoch-millis format + */ + timestamp: number; + /** + * Request volatile data + * @see https://docs.kuzzle.io/core/2/guides/essentials/volatile-data/ + */ + volatile: JSONObject; +} + +/** + * Notification triggered by a document change. + * (create, update, delete) + */ +export interface DocumentNotification extends BaseNotification { + /** + * Updated document that triggered the notification + */ + result: Document; + /** + * State of the document regarding the scope (`in` or `out`) + */ + scope: 'in' | 'out'; + + type: 'document'; +} + +/** + * Notification triggered by an user joining or leaving a subscription room + */ +export interface UserNotification extends BaseNotification { + /** + * Tell wether an user leave or join the subscription room (`in` or `out`) + */ + user: 'in' | 'out'; + + /** + * Contains the actual number of users in the subscription room + */ + result: { + /** + * Updated users count sharing the same subscription room + */ + count: number; + } + + type: 'user'; +} + +export interface ServerNotification extends BaseNotification { + /** + * Server message explaining why this notifications has been triggered + */ + message: string; + + type: 'TokenExpired'; +} \ No newline at end of file diff --git a/src/types/ProfilePolicy.ts b/src/types/ProfilePolicy.ts new file mode 100644 index 000000000..c00c01e09 --- /dev/null +++ b/src/types/ProfilePolicy.ts @@ -0,0 +1,40 @@ +/** + * A profile policy is composed of a roleId to define API rights + * and an optional array of restrictions on index and collections + * + * @example + * { + * "roleId": "editor", + * "restrictedTo": { + * "index": "blog", + * "collections": [ + * "articles" + * ] + * } + * } + * + * @see https://docs.kuzzle.io/core/2/guides/essentials/security/#defining-profiles + */ +export type ProfilePolicy = { + /** + * Role unique ID used by this policy + */ + roleId: string; + + /** + * Optional array of restrictions on which the rights are gonne be applied + */ + restrictedTo?: { + /** + * Index name. + * Rights will only be applied on this index. + */ + index: string; + + /** + * Collection names. + * Rights will only be applied on those collections. + */ + collections?: Array; + } +} diff --git a/src/types/RequestPayload.ts b/src/types/RequestPayload.ts new file mode 100644 index 000000000..79a07de0f --- /dev/null +++ b/src/types/RequestPayload.ts @@ -0,0 +1,55 @@ +import { JSONObject } from './JSONObject'; + +/** + * Kuzzle API request payload + * + * @see https://docs.kuzzle.io/core/2/api/payloads/request + */ +export type RequestPayload = { + /** + * API controller name + */ + controller?: string; + + /** + * API action name + */ + action?: string; + + /** + * Index name + */ + index?: string; + + /** + * Collection name + */ + collection?: string; + + /** + * Document unique identifier + */ + _id?: string; + + /** + * Authentication token + */ + jwt?: string; + + /** + * Volatile data + */ + volatile?: JSONObject; + + /** + * Request body + */ + body?: JSONObject; + + /** + * Request unique identifier + */ + requestId?: string; + + [key: string]: any; +} \ No newline at end of file diff --git a/src/types/ResponsePayload.ts b/src/types/ResponsePayload.ts new file mode 100644 index 000000000..3d01dd4ab --- /dev/null +++ b/src/types/ResponsePayload.ts @@ -0,0 +1,88 @@ +import { JSONObject } from './JSONObject'; + +/** + * Kuzzle API response payload + * + * @see https://docs.kuzzle.io/core/2/api/payloads/response + */ +export type ResponsePayload = { + /** + * API controller name + */ + controller: string; + + /** + * API action name + */ + action: string; + + /** + * Index name + */ + index?: string; + + /** + * Collection name + */ + collection?: string; + + /** + * Document unique identifier + */ + _id?: string; + + /** + * API error + */ + error?: { + /** + * Error human readable identifier + */ + id: string; + + /** + * Error identifier + */ + code: number; + + /** + * Error message + */ + message: string; + + /** + * HTTP status error code + */ + status: number; + + /** + * Error stacktrace (only if NODE_ENV=development) + */ + stack?: string; + }; + + /** + * Request unique identifier + */ + requestId: string; + + /** + * API action result + */ + result: any; + + /** + * HTTP status code + */ + status: number; + + /** + * Volatile data + */ + volatile?: JSONObject; + + /** + * Room unique identifier + */ + room?: string; +} diff --git a/src/types/RoleRightsDefinition.ts b/src/types/RoleRightsDefinition.ts new file mode 100644 index 000000000..747e7aae1 --- /dev/null +++ b/src/types/RoleRightsDefinition.ts @@ -0,0 +1,36 @@ +/** + * Role list of rights definition for controllers and actions. + * + * @example + * + * { + * auth: { + * actions: { + * getCurrentUser: true, + * getMyCredentials: true, + * getMyRights: true, + * logout: true + * } + * }, + * realtime: { + * actions: { + * "*": true + * } + * } + * } + * + * @see https://docs.kuzzle.io/core/2/guides/essentials/security#defining-roles + */ +export type RoleRightsDefinition = { + /** + * API controller name + */ + [controller: string]: { + actions: { + /** + * API action name + */ + [action: string]: boolean + } + } +} diff --git a/src/types/index.ts b/src/types/index.ts new file mode 100644 index 000000000..1196595df --- /dev/null +++ b/src/types/index.ts @@ -0,0 +1,15 @@ +export * from './ApiKey'; + +export * from './Document'; + +export * from './HttpRoutes'; + +export * from './JSONObject'; + +export * from './Mappings'; + +export * from './Notification'; + +export * from './ProfilePolicy'; + +export * from './RoleRightsDefinition'; diff --git a/src/utils/interfaces.ts b/src/utils/interfaces.ts deleted file mode 100644 index 5a669cd1b..000000000 --- a/src/utils/interfaces.ts +++ /dev/null @@ -1,442 +0,0 @@ -'use strict'; - -/** - * An interface representing an object with string key and any value - */ -export interface JSONObject { - [key: string]: JSONObject | any -} - -/** - * Kuzzle API request - * - * @see https://docs.kuzzle.io/core/2/guides/main-concepts/querying#other-protocols - */ -export interface KuzzleRequest extends JSONObject { - controller?: string; - action?: string; - index?: string; - collection?: string; - _id?: string; - jwt?: string; - volatile?: JSONObject; - body?: JSONObject; - [key: string]: any; -} - -/** - * Kuzzle API response - * - * @see https://docs.kuzzle.io/core/2/api/essentials/kuzzle-response/ - */ -export interface KuzzleResponse extends JSONObject { - controller: string; - action: string; - index?: string; - collection?: string; - error?: { - id: string; - code: number; - message: string; - status: number; - stack?: string; - }; - requestId: string; - result: JSONObject | null; - status: number; - volatile?: JSONObject; - room?: string; -} - -/** - * A profile policy is composed of a roleId to define API rights - * and an optional array of restrictions on index and collections - * - * @example - * { - * "roleId": "editor", - * "restrictedTo": { - * "index": "blog", - * "collections": [ - * "articles" - * ] - * } - * } - * - * @see https://docs.kuzzle.io/core/2/guides/main-concepts/permissions#profiles - */ -export interface ProfilePolicy { - /** - * Role unique ID used by this policy - */ - roleId: string; - - /** - * Optional array of restrictions on which the rights are gonne be applied - */ - restrictedTo?: { - /** - * Index name. - * Rights will only be applied on this index. - */ - index: string; - - /** - * Collection names. - * Rights will only be applied on those collections. - */ - collections?: Array; - } -} - -/** - * Role list of rights definition for controllers and actions. - * - * @example - * - * { - * auth: { - * actions: { - * getCurrentUser: true, - * getMyCredentials: true, - * getMyRights: true, - * logout: true - * } - * }, - * realtime: { - * actions: { - * "*": true - * } - * } - * } - * - * @see https://docs.kuzzle.io/core/2/guides/main-concepts/permissions#roles - */ -export interface RoleRightsDefinition { - /** - * API controller name - */ - [key: string]: { - actions: { - /** - * API action name - */ - [key: string]: boolean - } - } -} - -/** - * ApiKey - */ -export interface ApiKey { - /** - * ApiKey unique ID - */ - _id: string; - /** - * ApiKey content - */ - _source: { - /** - * User kuid - */ - userId: string; - /** - * Expiration date in Epoch-millis format (-1 if the token never expires) - */ - expiresAt: number; - /** - * Original TTL in ms - */ - ttl: number; - /** - * API key description - */ - description: string; - /** - * Authentication token associated with this API key - */ - token: string; - } -} - -/** - * Kuzzle metadata - * @see https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage#kuzzle-metadata - */ -export interface KuzzleMetadata { - _kuzzle_info: { - /** - * Kuid of the user who created the document - */ - author: string, - /** - * Creation date in micro-timestamp - */ - createdAt: number, - /** - * Kuid of the user who last updated the document - */ - updater: string | null, - /** - * Update date in micro-timestamp - */ - updatedAt: number | null - } -} - -/** - * Represents the `_source` property of the document - */ -export interface DocumentContent extends KuzzleMetadata { - [key: string]: JSONObject | any, -} - -/** - * Kuzzle document - * - * @property _id - * @property _version - * @property _source - */ -export class Document { - /** - * Document unique ID - */ - _id: string; - /** - * Document Version (generated by Elasticsearch) - */ - _version?: number; - /** - * Document Content - */ - _source: DocumentContent; -} - -/** - * Document retrieved from a search - * - * @property _id - * @property _version - * @property _source - * @property _score - */ -export interface DocumentHit extends Document { - /** - * Relevance score - */ - _score: number; -} - -export interface MappingsProperties { - /** - * Properties types definition - * - * @see https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage#properties-types-definition - */ - properties?: MappingsProperties, - /** - * Dynamic mapping policy - * - * @see https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage#mappings-dynamic-policy - */ - dynamic?: 'true' | 'false' | 'strict' | boolean -} - -/** - * Collection mappings definition - * - * @see https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage - */ -export interface CollectionMappings { - /** - * Collection metadata - * - * @see https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage#collection-metadata - */ - _meta?: JSONObject; - /** - * Properties types definition - * - * @see https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage#properties-types-definition - */ - properties?: MappingsProperties, - /** - * Dynamic mapping policy - * - * @see https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage#mappings-dynamic-policy - */ - dynamic?: 'true' | 'false' | 'strict' | boolean, -} - -/** - * Enum for notification types - */ -export enum ENotificationType { - document = 'document', - user = 'user', - TokenExpired = 'TokenExpired' -} - -/** - * Real-time notifications sent by Kuzzle. - * - */ -export interface Notification { - /** - * Notification type - */ - type: ENotificationType; -} - -export interface BaseNotification extends Notification { - /** - * Controller that triggered the notification - */ - controller: string; - /** - * Action that triggered the notification - */ - action: string; - /** - * Index name - */ - index: string; - /** - * Collection name - */ - collection: string; - /** - * Network protocol used to trigger the notification - */ - protocol: string; - /** - * Subscription channel identifier. - * Can be used to link a notification to its corresponding subscription - */ - room: string; - /** - * Timestamp of the event, in Epoch-millis format - */ - timestamp: number; - /** - * Request volatile data - * @see https://docs.kuzzle.io/core/2/guides/main-concepts/api#volatile-data/ - */ - volatile: JSONObject; -} - -/** - * State of the document regarding the scope - */ -export enum EDocumentScope { - /** - * Document enters or stays in the scope - */ - in = 'in', - /** - * Document exit the scope - */ - out = 'out' -} - -/** - * Notification triggered by a document change. - * (create, update, delete) - */ -export interface DocumentNotification extends BaseNotification { - /** - * Updated document that triggered the notification - */ - result: Document; - /** - * State of the document regarding the scope (`in` or `out`) - */ - scope: EDocumentScope; - - type: ENotificationType.document; -} - -/** - * Tells wether an user leave or join the subscription room - */ -export enum EUserScope { - /** - * User enters the subscription room - */ - in = 'in', - /** - * User leaves the subscription room - */ - out = 'out' -} - -/** - * Notification triggered by an user joining or leaving a subscription room - */ -export interface UserNotification extends BaseNotification { - /** - * Tell wether an user leave or join the subscription room (`in` or `out`) - */ - user: EUserScope; - - /** - * Contains the actual number of users in the subscription room - */ - result: { - /** - * Updated users count sharing the same subscription room - */ - count: number; - } - - type: ENotificationType.user; -} - -export interface ServerNotification extends BaseNotification { - /** - * Server message explaining why this notifications has been triggered - */ - message: string; - - type: ENotificationType.TokenExpired; -} - -/** - * HTTP routes definition format - * @example - * { - * : { - * : { verb: , url: } - * } - * } - * - * { - * 'my-plugin/my-controller': { - * action: { verb: 'GET', url: '/some/url' }, - * action2: { verb: 'GET', url: '/some/url/with/:parameter' } - * } - * } - */ -export interface HttpRoutes { - /** - * Controller name - */ - [key: string]: { - /** - * Action name - */ - [key: string]: { - /** - * HTTP verb - */ - verb: string, - /** - * URL - */ - url: string - } - } -}