From 47d761f6f1fe12e5856097940bebf63ca727776b Mon Sep 17 00:00:00 2001 From: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Date: Wed, 5 May 2021 12:45:41 -0400 Subject: [PATCH] Document plugin API for `spaces` and `spacesOss` (#98966) (#99355) Co-authored-by: Joe Portner <5295965+jportner@users.noreply.github.com> Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com> Co-authored-by: Larry Gregory Co-authored-by: Joe Portner <5295965+jportner@users.noreply.github.com> --- api_docs/spaces.json | 895 ++++++++++++++---- api_docs/spaces_oss.json | 313 +++--- src/plugins/spaces_oss/common/types.ts | 48 +- src/plugins/spaces_oss/public/api.ts | 45 +- src/plugins/spaces_oss/public/index.ts | 4 +- src/plugins/spaces_oss/public/types.ts | 20 + .../server/lib/check_access.test.ts | 2 +- .../spaces/common/lib/spaces_url_parser.ts | 18 + x-pack/plugins/spaces/common/types.ts | 29 + x-pack/plugins/spaces/public/plugin.tsx | 7 + .../public/space_avatar/space_attributes.ts | 6 +- x-pack/plugins/spaces/server/config.test.ts | 2 +- x-pack/plugins/spaces/server/config.ts | 2 +- x-pack/plugins/spaces/server/index.ts | 2 +- x-pack/plugins/spaces/server/plugin.test.ts | 2 +- x-pack/plugins/spaces/server/plugin.ts | 26 + .../server/spaces_client/spaces_client.ts | 42 +- .../spaces_client/spaces_client_service.ts | 8 + .../server/spaces_service/spaces_service.ts | 35 +- .../spaces_usage_collector.ts | 4 +- .../schema/xpack_plugins.json | 4 +- .../tests_client_integration/overview.test.ts | 2 +- 22 files changed, 1149 insertions(+), 367 deletions(-) diff --git a/api_docs/spaces.json b/api_docs/spaces.json index 299bba81678a..d633b0e653e1 100644 --- a/api_docs/spaces.json +++ b/api_docs/spaces.json @@ -38,7 +38,9 @@ }, ">" ], - "description": [], + "description": [ + "the space." + ], "source": { "path": "x-pack/plugins/spaces/public/space_avatar/space_attributes.ts", "lineNumber": 24 @@ -88,7 +90,9 @@ }, ">" ], - "description": [], + "description": [ + "the space." + ], "source": { "path": "x-pack/plugins/spaces/public/space_avatar/space_attributes.ts", "lineNumber": 64 @@ -138,7 +142,9 @@ }, ">" ], - "description": [], + "description": [ + "the space." + ], "source": { "path": "x-pack/plugins/spaces/public/space_avatar/space_attributes.ts", "lineNumber": 43 @@ -176,7 +182,9 @@ "text": "Space" } ], - "description": [], + "description": [ + "\nResponse format when querying for spaces." + ], "tags": [], "children": [ { @@ -184,10 +192,12 @@ "id": "def-public.GetSpaceResult.authorizedPurposes", "type": "Object", "label": "authorizedPurposes", - "description": [], + "description": [ + "\nA set of flags indicating which purposes the user is authorized for." + ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 22 + "lineNumber": 51 }, "signature": [ "Record<", @@ -204,7 +214,7 @@ ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 21 + "lineNumber": 47 }, "initialIsOpen": false }, @@ -212,7 +222,9 @@ "id": "def-public.Space", "type": "Interface", "label": "Space", - "description": [], + "description": [ + "\nA Kibana Space." + ], "tags": [], "children": [ { @@ -220,10 +232,12 @@ "id": "def-public.Space.id", "type": "string", "label": "id", - "description": [], + "description": [ + "\nThe unique identifier for this space.\nThe id becomes part of the \"URL Identifier\" of the space.\n\nExample: an id of `marketing` would result in the URL identifier of `/s/marketing`." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 10 + "lineNumber": 19 } }, { @@ -231,10 +245,12 @@ "id": "def-public.Space.name", "type": "string", "label": "name", - "description": [], + "description": [ + "\nDisplay name for this space." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 11 + "lineNumber": 24 } }, { @@ -242,10 +258,12 @@ "id": "def-public.Space.description", "type": "string", "label": "description", - "description": [], + "description": [ + "\nOptional description for this space." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 12 + "lineNumber": 29 }, "signature": [ "string | undefined" @@ -256,10 +274,12 @@ "id": "def-public.Space.color", "type": "string", "label": "color", - "description": [], + "description": [ + "\nOptional color (hex code) for this space.\nIf neither `color` nor `imageUrl` is specified, then a color will be automatically generated." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 13 + "lineNumber": 35 }, "signature": [ "string | undefined" @@ -270,10 +290,28 @@ "id": "def-public.Space.initials", "type": "string", "label": "initials", - "description": [], + "description": [ + "\nOptional display initials for this space's avatar. Supports a maximum of 2 characters.\nIf initials are not provided, then they will be derived from the space name automatically.\n\nInitials are not displayed if an `imageUrl` has been specified." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 14 + "lineNumber": 43 + }, + "signature": [ + "string | undefined" + ] + }, + { + "tags": [], + "id": "def-public.Space.imageUrl", + "type": "string", + "label": "imageUrl", + "description": [ + "\nOptional base-64 encoded data image url to show as this space's avatar.\nThis setting takes precedence over any configured `color` or `initials`." + ], + "source": { + "path": "src/plugins/spaces_oss/common/types.ts", + "lineNumber": 49 }, "signature": [ "string | undefined" @@ -284,47 +322,39 @@ "id": "def-public.Space.disabledFeatures", "type": "Array", "label": "disabledFeatures", - "description": [], + "description": [ + "\nThe set of feature ids that should be hidden within this space." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 15 + "lineNumber": 54 }, "signature": [ "string[]" ] }, { - "tags": [], + "tags": [ + "private" + ], "id": "def-public.Space._reserved", "type": "CompoundType", "label": "_reserved", - "description": [], + "description": [ + "\nIndicates that this space is reserved (system controlled).\nReserved spaces cannot be created or deleted by end-users." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 16 + "lineNumber": 61 }, "signature": [ "boolean | undefined" ] - }, - { - "tags": [], - "id": "def-public.Space.imageUrl", - "type": "string", - "label": "imageUrl", - "description": [], - "source": { - "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 17 - }, - "signature": [ - "string | undefined" - ] } ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 9 + "lineNumber": 12 }, "initialIsOpen": false } @@ -336,10 +366,12 @@ "type": "Type", "label": "GetAllSpacesPurpose", "tags": [], - "description": [], + "description": [ + "\nThe set of purposes to retrieve spaces:\n- `any`: retrieves all spaces the user is authorized to see.\n- `copySavedObjectsIntoSpace`: retrieves all spaces the user is authorized to copy saved objects into.\n- `findSavedObjects`: retrieves all spaces the user is authorized to search within.\n- `shareSavedObjectsIntoSpace`: retrieves all spaces the user is authorized to share saved objects into." + ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 15 + "lineNumber": 38 }, "signature": [ "\"any\" | \"copySavedObjectsIntoSpace\" | \"findSavedObjects\" | \"shareSavedObjectsIntoSpace\"" @@ -353,10 +385,12 @@ "type": "Type", "label": "SpacesPluginSetup", "tags": [], - "description": [], + "description": [ + "\nSetup contract for the Spaces plugin." + ], "source": { "path": "x-pack/plugins/spaces/public/plugin.tsx", - "lineNumber": 39 + "lineNumber": 42 }, "signature": [ "{}" @@ -369,10 +403,12 @@ "type": "Type", "label": "SpacesPluginStart", "tags": [], - "description": [], + "description": [ + "\nStart contract for the Spaces plugin." + ], "source": { "path": "x-pack/plugins/spaces/public/plugin.tsx", - "lineNumber": 40 + "lineNumber": 47 }, "signature": [ "SpacesApi" @@ -391,7 +427,9 @@ "signature": [ "(basePath: string, spaceId: string, requestedPath: string) => string" ], - "description": [], + "description": [ + "\nGiven a server base path, space id, and requested resource, this will construct a space-aware path\nthat includes a URL identifier with the space id.\n" + ], "children": [ { "id": "def-server.addSpaceIdToPath.$1", @@ -401,10 +439,12 @@ "signature": [ "string" ], - "description": [], + "description": [ + "the server's base path." + ], "source": { "path": "x-pack/plugins/spaces/common/lib/spaces_url_parser.ts", - "lineNumber": 44 + "lineNumber": 62 } }, { @@ -415,10 +455,12 @@ "signature": [ "string" ], - "description": [], + "description": [ + "the space id." + ], "source": { "path": "x-pack/plugins/spaces/common/lib/spaces_url_parser.ts", - "lineNumber": 45 + "lineNumber": 63 } }, { @@ -429,18 +471,22 @@ "signature": [ "string" ], - "description": [], + "description": [ + "the requested path (e.g. `/app/dashboard`)." + ], "source": { "path": "x-pack/plugins/spaces/common/lib/spaces_url_parser.ts", - "lineNumber": 46 + "lineNumber": 64 } } ], "tags": [], - "returnComment": [], + "returnComment": [ + "the space-aware version of the requested path, inclusive of the server's base path." + ], "source": { "path": "x-pack/plugins/spaces/common/lib/spaces_url_parser.ts", - "lineNumber": 43 + "lineNumber": 61 }, "initialIsOpen": false } @@ -450,32 +496,42 @@ "id": "def-server.GetAllSpacesOptions", "type": "Interface", "label": "GetAllSpacesOptions", - "description": [], + "description": [ + "\nControls how spaces are retrieved." + ], "tags": [], "children": [ { - "tags": [], + "tags": [ + "see" + ], "id": "def-server.GetAllSpacesOptions.purpose", "type": "CompoundType", "label": "purpose", - "description": [], + "description": [ + "\nAn optional purpose describing how the set of spaces will be used.\nThe default purpose (`any`) will retrieve all spaces the user is authorized to see,\nwhereas a more specific purpose will retrieve all spaces the user is authorized to perform a specific action within.\n" + ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 11 + "lineNumber": 21 }, "signature": [ "\"any\" | \"copySavedObjectsIntoSpace\" | \"findSavedObjects\" | \"shareSavedObjectsIntoSpace\" | undefined" ] }, { - "tags": [], + "tags": [ + "see" + ], "id": "def-server.GetAllSpacesOptions.includeAuthorizedPurposes", "type": "CompoundType", "label": "includeAuthorizedPurposes", - "description": [], + "description": [ + "\nSet to true to return a set of flags indicating which purposes the user is authorized for.\n" + ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 12 + "lineNumber": 28 }, "signature": [ "boolean | undefined" @@ -484,7 +540,7 @@ ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 10 + "lineNumber": 13 }, "initialIsOpen": false }, @@ -509,7 +565,9 @@ "text": "Space" } ], - "description": [], + "description": [ + "\nResponse format when querying for spaces." + ], "tags": [], "children": [ { @@ -517,10 +575,12 @@ "id": "def-server.GetSpaceResult.authorizedPurposes", "type": "Object", "label": "authorizedPurposes", - "description": [], + "description": [ + "\nA set of flags indicating which purposes the user is authorized for." + ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 22 + "lineNumber": 51 }, "signature": [ "Record<", @@ -537,7 +597,289 @@ ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 21 + "lineNumber": 47 + }, + "initialIsOpen": false + }, + { + "id": "def-server.ISpacesClient", + "type": "Interface", + "label": "ISpacesClient", + "description": [ + "\nClient interface for interacting with spaces." + ], + "tags": [], + "children": [ + { + "id": "def-server.ISpacesClient.getAll", + "type": "Function", + "label": "getAll", + "signature": [ + "(options?: ", + { + "pluginId": "spaces", + "scope": "common", + "docId": "kibSpacesPluginApi", + "section": "def-common.GetAllSpacesOptions", + "text": "GetAllSpacesOptions" + }, + " | undefined) => Promise<", + { + "pluginId": "spaces", + "scope": "common", + "docId": "kibSpacesPluginApi", + "section": "def-common.GetSpaceResult", + "text": "GetSpaceResult" + }, + "[]>" + ], + "description": [ + "\nRetrieve all available spaces." + ], + "children": [ + { + "id": "def-server.ISpacesClient.getAll.$1", + "type": "Object", + "label": "options", + "isRequired": false, + "signature": [ + { + "pluginId": "spaces", + "scope": "common", + "docId": "kibSpacesPluginApi", + "section": "def-common.GetAllSpacesOptions", + "text": "GetAllSpacesOptions" + }, + " | undefined" + ], + "description": [ + "controls which spaces are retrieved." + ], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 34 + } + } + ], + "tags": [], + "returnComment": [], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 34 + } + }, + { + "id": "def-server.ISpacesClient.get", + "type": "Function", + "label": "get", + "signature": [ + "(id: string) => Promise<", + { + "pluginId": "spacesOss", + "scope": "common", + "docId": "kibSpacesOssPluginApi", + "section": "def-common.Space", + "text": "Space" + }, + ">" + ], + "description": [ + "\nRetrieve a space by its id." + ], + "children": [ + { + "id": "def-server.ISpacesClient.get.$1", + "type": "string", + "label": "id", + "isRequired": true, + "signature": [ + "string" + ], + "description": [ + "the space id." + ], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 40 + } + } + ], + "tags": [], + "returnComment": [], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 40 + } + }, + { + "id": "def-server.ISpacesClient.create", + "type": "Function", + "label": "create", + "signature": [ + "(space: ", + { + "pluginId": "spacesOss", + "scope": "common", + "docId": "kibSpacesOssPluginApi", + "section": "def-common.Space", + "text": "Space" + }, + ") => Promise<", + { + "pluginId": "spacesOss", + "scope": "common", + "docId": "kibSpacesOssPluginApi", + "section": "def-common.Space", + "text": "Space" + }, + ">" + ], + "description": [ + "\nCreates a space." + ], + "children": [ + { + "id": "def-server.ISpacesClient.create.$1", + "type": "Object", + "label": "space", + "isRequired": true, + "signature": [ + { + "pluginId": "spacesOss", + "scope": "common", + "docId": "kibSpacesOssPluginApi", + "section": "def-common.Space", + "text": "Space" + } + ], + "description": [ + "the space to create." + ], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 46 + } + } + ], + "tags": [], + "returnComment": [], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 46 + } + }, + { + "id": "def-server.ISpacesClient.update", + "type": "Function", + "label": "update", + "signature": [ + "(id: string, space: ", + { + "pluginId": "spacesOss", + "scope": "common", + "docId": "kibSpacesOssPluginApi", + "section": "def-common.Space", + "text": "Space" + }, + ") => Promise<", + { + "pluginId": "spacesOss", + "scope": "common", + "docId": "kibSpacesOssPluginApi", + "section": "def-common.Space", + "text": "Space" + }, + ">" + ], + "description": [ + "\nUpdates a space." + ], + "children": [ + { + "id": "def-server.ISpacesClient.update.$1", + "type": "string", + "label": "id", + "isRequired": true, + "signature": [ + "string" + ], + "description": [ + "the id of the space to update." + ], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 53 + } + }, + { + "id": "def-server.ISpacesClient.update.$2", + "type": "Object", + "label": "space", + "isRequired": true, + "signature": [ + { + "pluginId": "spacesOss", + "scope": "common", + "docId": "kibSpacesOssPluginApi", + "section": "def-common.Space", + "text": "Space" + } + ], + "description": [ + "the updated space." + ], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 53 + } + } + ], + "tags": [], + "returnComment": [], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 53 + } + }, + { + "id": "def-server.ISpacesClient.delete", + "type": "Function", + "label": "delete", + "signature": [ + "(id: string) => Promise" + ], + "description": [ + "\nDeletes a space, and all saved objects belonging to that space." + ], + "children": [ + { + "id": "def-server.ISpacesClient.delete.$1", + "type": "string", + "label": "id", + "isRequired": true, + "signature": [ + "string" + ], + "description": [ + "the id of the space to delete." + ], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 59 + } + } + ], + "tags": [], + "returnComment": [], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 59 + } + } + ], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", + "lineNumber": 29 }, "initialIsOpen": false }, @@ -545,7 +887,9 @@ "id": "def-server.Space", "type": "Interface", "label": "Space", - "description": [], + "description": [ + "\nA Kibana Space." + ], "tags": [], "children": [ { @@ -553,10 +897,12 @@ "id": "def-server.Space.id", "type": "string", "label": "id", - "description": [], + "description": [ + "\nThe unique identifier for this space.\nThe id becomes part of the \"URL Identifier\" of the space.\n\nExample: an id of `marketing` would result in the URL identifier of `/s/marketing`." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 10 + "lineNumber": 19 } }, { @@ -564,10 +910,12 @@ "id": "def-server.Space.name", "type": "string", "label": "name", - "description": [], + "description": [ + "\nDisplay name for this space." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 11 + "lineNumber": 24 } }, { @@ -575,10 +923,12 @@ "id": "def-server.Space.description", "type": "string", "label": "description", - "description": [], + "description": [ + "\nOptional description for this space." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 12 + "lineNumber": 29 }, "signature": [ "string | undefined" @@ -589,10 +939,12 @@ "id": "def-server.Space.color", "type": "string", "label": "color", - "description": [], + "description": [ + "\nOptional color (hex code) for this space.\nIf neither `color` nor `imageUrl` is specified, then a color will be automatically generated." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 13 + "lineNumber": 35 }, "signature": [ "string | undefined" @@ -603,10 +955,28 @@ "id": "def-server.Space.initials", "type": "string", "label": "initials", - "description": [], + "description": [ + "\nOptional display initials for this space's avatar. Supports a maximum of 2 characters.\nIf initials are not provided, then they will be derived from the space name automatically.\n\nInitials are not displayed if an `imageUrl` has been specified." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 14 + "lineNumber": 43 + }, + "signature": [ + "string | undefined" + ] + }, + { + "tags": [], + "id": "def-server.Space.imageUrl", + "type": "string", + "label": "imageUrl", + "description": [ + "\nOptional base-64 encoded data image url to show as this space's avatar.\nThis setting takes precedence over any configured `color` or `initials`." + ], + "source": { + "path": "src/plugins/spaces_oss/common/types.ts", + "lineNumber": 49 }, "signature": [ "string | undefined" @@ -617,47 +987,39 @@ "id": "def-server.Space.disabledFeatures", "type": "Array", "label": "disabledFeatures", - "description": [], + "description": [ + "\nThe set of feature ids that should be hidden within this space." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 15 + "lineNumber": 54 }, "signature": [ "string[]" ] }, { - "tags": [], + "tags": [ + "private" + ], "id": "def-server.Space._reserved", "type": "CompoundType", "label": "_reserved", - "description": [], + "description": [ + "\nIndicates that this space is reserved (system controlled).\nReserved spaces cannot be created or deleted by end-users." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 16 + "lineNumber": 61 }, "signature": [ "boolean | undefined" ] - }, - { - "tags": [], - "id": "def-server.Space.imageUrl", - "type": "string", - "label": "imageUrl", - "description": [], - "source": { - "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 17 - }, - "signature": [ - "string | undefined" - ] } ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 9 + "lineNumber": 12 }, "initialIsOpen": false }, @@ -665,7 +1027,9 @@ "id": "def-server.SpacesServiceSetup", "type": "Interface", "label": "SpacesServiceSetup", - "description": [], + "description": [ + "\nThe Spaces service setup contract." + ], "tags": [], "children": [ { @@ -702,20 +1066,23 @@ }, "" ], - "description": [], + "description": [ + "the request." + ], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 23 + "lineNumber": 27 } } ], "tags": [ - "deprecated" + "deprecated", + "removeBy" ], "returnComment": [], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 23 + "lineNumber": 27 } }, { @@ -737,20 +1104,23 @@ "signature": [ "string" ], - "description": [], + "description": [ + "the space id to convert." + ], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 31 + "lineNumber": 36 } } ], "tags": [ - "deprecated" + "deprecated", + "removeBy" ], "returnComment": [], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 31 + "lineNumber": 36 } }, { @@ -772,26 +1142,29 @@ "signature": [ "string | undefined" ], - "description": [], + "description": [ + "the namespace to convert." + ], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 39 + "lineNumber": 45 } } ], "tags": [ - "deprecated" + "deprecated", + "removeBy" ], "returnComment": [], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 39 + "lineNumber": 45 } } ], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 16 + "lineNumber": 19 }, "initialIsOpen": false }, @@ -799,7 +1172,9 @@ "id": "def-server.SpacesServiceStart", "type": "Interface", "label": "SpacesServiceStart", - "description": [], + "description": [ + "\nThe Spaces service start contract." + ], "tags": [], "children": [ { @@ -812,7 +1187,7 @@ ], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 46 + "lineNumber": 56 }, "signature": [ "(request: ", @@ -823,9 +1198,14 @@ "section": "def-server.KibanaRequest", "text": "KibanaRequest" }, - ") => Pick<", - "SpacesClient", - ", \"get\" | \"delete\" | \"create\" | \"update\" | \"getAll\">" + ") => ", + { + "pluginId": "spaces", + "scope": "server", + "docId": "kibSpacesPluginApi", + "section": "def-server.ISpacesClient", + "text": "ISpacesClient" + } ] }, { @@ -862,10 +1242,12 @@ }, "" ], - "description": [], + "description": [ + "the request." + ], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 52 + "lineNumber": 62 } } ], @@ -873,7 +1255,7 @@ "returnComment": [], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 52 + "lineNumber": 62 } }, { @@ -910,10 +1292,12 @@ }, "" ], - "description": [], + "description": [ + "the request." + ], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 58 + "lineNumber": 68 } } ], @@ -921,7 +1305,7 @@ "returnComment": [], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 58 + "lineNumber": 68 } }, { @@ -966,10 +1350,12 @@ }, "" ], - "description": [], + "description": [ + "the request." + ], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 64 + "lineNumber": 74 } } ], @@ -977,7 +1363,7 @@ "returnComment": [], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 64 + "lineNumber": 74 } }, { @@ -999,10 +1385,12 @@ "signature": [ "string" ], - "description": [], + "description": [ + "the space id to convert." + ], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 70 + "lineNumber": 80 } } ], @@ -1010,7 +1398,7 @@ "returnComment": [], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 70 + "lineNumber": 80 } }, { @@ -1032,10 +1420,12 @@ "signature": [ "string | undefined" ], - "description": [], + "description": [ + "the namespace to convert." + ], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 76 + "lineNumber": 86 } } ], @@ -1043,13 +1433,13 @@ "returnComment": [], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 76 + "lineNumber": 86 } } ], "source": { "path": "x-pack/plugins/spaces/server/spaces_service/spaces_service.ts", - "lineNumber": 42 + "lineNumber": 51 }, "initialIsOpen": false } @@ -1061,10 +1451,12 @@ "type": "Type", "label": "GetAllSpacesPurpose", "tags": [], - "description": [], + "description": [ + "\nThe set of purposes to retrieve spaces:\n- `any`: retrieves all spaces the user is authorized to see.\n- `copySavedObjectsIntoSpace`: retrieves all spaces the user is authorized to copy saved objects into.\n- `findSavedObjects`: retrieves all spaces the user is authorized to search within.\n- `shareSavedObjectsIntoSpace`: retrieves all spaces the user is authorized to share saved objects into." + ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 15 + "lineNumber": 38 }, "signature": [ "\"any\" | \"copySavedObjectsIntoSpace\" | \"findSavedObjects\" | \"shareSavedObjectsIntoSpace\"" @@ -1072,17 +1464,87 @@ "initialIsOpen": false }, { - "id": "def-server.ISpacesClient", + "id": "def-server.SpacesClientRepositoryFactory", "type": "Type", - "label": "ISpacesClient", - "tags": [], - "description": [], + "label": "SpacesClientRepositoryFactory", + "tags": [ + "private" + ], + "description": [ + "\nFor consumption by the security plugin only." + ], "source": { - "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client.ts", - "lineNumber": 27 + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client_service.ts", + "lineNumber": 34 }, "signature": [ - "{ get: (id: string) => Promise; delete: (id: string) => Promise; create: (space: Space) => Promise; update: (id: string, space: Space) => Promise; getAll: (options?: GetAllSpacesOptions) => Promise; }" + "(request: ", + { + "pluginId": "core", + "scope": "server", + "docId": "kibCoreHttpPluginApi", + "section": "def-server.KibanaRequest", + "text": "KibanaRequest" + }, + ", savedObjectsStart: ", + { + "pluginId": "core", + "scope": "server", + "docId": "kibCoreSavedObjectsPluginApi", + "section": "def-server.SavedObjectsServiceStart", + "text": "SavedObjectsServiceStart" + }, + ") => Pick<", + { + "pluginId": "core", + "scope": "server", + "docId": "kibCoreSavedObjectsPluginApi", + "section": "def-server.SavedObjectsRepository", + "text": "SavedObjectsRepository" + }, + ", \"get\" | \"delete\" | \"create\" | \"bulkCreate\" | \"checkConflicts\" | \"deleteByNamespace\" | \"find\" | \"bulkGet\" | \"resolve\" | \"update\" | \"addToNamespaces\" | \"deleteFromNamespaces\" | \"bulkUpdate\" | \"removeReferencesTo\" | \"incrementCounter\" | \"openPointInTimeForType\" | \"closePointInTime\" | \"createPointInTimeFinder\">" + ], + "initialIsOpen": false + }, + { + "id": "def-server.SpacesClientWrapper", + "type": "Type", + "label": "SpacesClientWrapper", + "tags": [ + "private" + ], + "description": [ + "\nFor consumption by the security plugin only." + ], + "source": { + "path": "x-pack/plugins/spaces/server/spaces_client/spaces_client_service.ts", + "lineNumber": 25 + }, + "signature": [ + "(request: ", + { + "pluginId": "core", + "scope": "server", + "docId": "kibCoreHttpPluginApi", + "section": "def-server.KibanaRequest", + "text": "KibanaRequest" + }, + ", baseClient: ", + { + "pluginId": "spaces", + "scope": "server", + "docId": "kibSpacesPluginApi", + "section": "def-server.ISpacesClient", + "text": "ISpacesClient" + }, + ") => ", + { + "pluginId": "spaces", + "scope": "server", + "docId": "kibSpacesPluginApi", + "section": "def-server.ISpacesClient", + "text": "ISpacesClient" + } ], "initialIsOpen": false } @@ -1092,18 +1554,25 @@ "id": "def-server.SpacesPluginSetup", "type": "Interface", "label": "SpacesPluginSetup", - "description": [], + "description": [ + "\nSetup contract for the Spaces plugin." + ], "tags": [], "children": [ { - "tags": [], + "tags": [ + "deprecated", + "removeBy" + ], "id": "def-server.SpacesPluginSetup.spacesService", "type": "Object", "label": "spacesService", - "description": [], + "description": [ + "\nService for interacting with spaces.\n" + ], "source": { "path": "x-pack/plugins/spaces/server/plugin.ts", - "lineNumber": 55 + "lineNumber": 64 }, "signature": [ { @@ -1116,27 +1585,43 @@ ] }, { - "tags": [], + "tags": [ + "private" + ], "id": "def-server.SpacesPluginSetup.spacesClient", "type": "Object", "label": "spacesClient", - "description": [], + "description": [ + "\nRegistries exposed for the security plugin to transparently provide authorization and audit logging." + ], "source": { "path": "x-pack/plugins/spaces/server/plugin.ts", - "lineNumber": 56 + "lineNumber": 70 }, "signature": [ "{ setClientRepositoryFactory: (factory: ", - "SpacesClientRepositoryFactory", + { + "pluginId": "spaces", + "scope": "server", + "docId": "kibSpacesPluginApi", + "section": "def-server.SpacesClientRepositoryFactory", + "text": "SpacesClientRepositoryFactory" + }, ") => void; registerClientWrapper: (wrapper: ", - "SpacesClientWrapper", + { + "pluginId": "spaces", + "scope": "server", + "docId": "kibSpacesPluginApi", + "section": "def-server.SpacesClientWrapper", + "text": "SpacesClientWrapper" + }, ") => void; }" ] } ], "source": { "path": "x-pack/plugins/spaces/server/plugin.ts", - "lineNumber": 54 + "lineNumber": 57 }, "lifecycle": "setup", "initialIsOpen": true @@ -1145,7 +1630,9 @@ "id": "def-server.SpacesPluginStart", "type": "Interface", "label": "SpacesPluginStart", - "description": [], + "description": [ + "\nStart contract for the Spaces plugin." + ], "tags": [], "children": [ { @@ -1153,10 +1640,12 @@ "id": "def-server.SpacesPluginStart.spacesService", "type": "Object", "label": "spacesService", - "description": [], + "description": [ + "Service for interacting with spaces." + ], "source": { "path": "x-pack/plugins/spaces/server/plugin.ts", - "lineNumber": 63 + "lineNumber": 89 }, "signature": [ { @@ -1171,7 +1660,7 @@ ], "source": { "path": "x-pack/plugins/spaces/server/plugin.ts", - "lineNumber": 62 + "lineNumber": 87 }, "lifecycle": "start", "initialIsOpen": true @@ -1187,7 +1676,9 @@ "signature": [ "(basePath: string, spaceId: string, requestedPath: string) => string" ], - "description": [], + "description": [ + "\nGiven a server base path, space id, and requested resource, this will construct a space-aware path\nthat includes a URL identifier with the space id.\n" + ], "children": [ { "id": "def-common.addSpaceIdToPath.$1", @@ -1197,10 +1688,12 @@ "signature": [ "string" ], - "description": [], + "description": [ + "the server's base path." + ], "source": { "path": "x-pack/plugins/spaces/common/lib/spaces_url_parser.ts", - "lineNumber": 44 + "lineNumber": 62 } }, { @@ -1211,10 +1704,12 @@ "signature": [ "string" ], - "description": [], + "description": [ + "the space id." + ], "source": { "path": "x-pack/plugins/spaces/common/lib/spaces_url_parser.ts", - "lineNumber": 45 + "lineNumber": 63 } }, { @@ -1225,18 +1720,22 @@ "signature": [ "string" ], - "description": [], + "description": [ + "the requested path (e.g. `/app/dashboard`)." + ], "source": { "path": "x-pack/plugins/spaces/common/lib/spaces_url_parser.ts", - "lineNumber": 46 + "lineNumber": 64 } } ], "tags": [], - "returnComment": [], + "returnComment": [ + "the space-aware version of the requested path, inclusive of the server's base path." + ], "source": { "path": "x-pack/plugins/spaces/common/lib/spaces_url_parser.ts", - "lineNumber": 43 + "lineNumber": 61 }, "initialIsOpen": false }, @@ -1247,7 +1746,9 @@ "signature": [ "(requestBasePath: string | null | undefined, serverBasePath: string | null | undefined) => { spaceId: string; pathHasExplicitSpaceIdentifier: boolean; }" ], - "description": [], + "description": [ + "\nExtracts the space id from the given path.\n" + ], "children": [ { "id": "def-common.getSpaceIdFromPath.$1", @@ -1257,10 +1758,12 @@ "signature": [ "string | null | undefined" ], - "description": [], + "description": [ + "The base path of the current request." + ], "source": { "path": "x-pack/plugins/spaces/common/lib/spaces_url_parser.ts", - "lineNumber": 13 + "lineNumber": 22 } }, { @@ -1271,18 +1774,24 @@ "signature": [ "string | null | undefined" ], - "description": [], + "description": [ + "The server's base path." + ], "source": { "path": "x-pack/plugins/spaces/common/lib/spaces_url_parser.ts", - "lineNumber": 14 + "lineNumber": 23 } } ], - "tags": [], - "returnComment": [], + "tags": [ + "private" + ], + "returnComment": [ + "the space id." + ], "source": { "path": "x-pack/plugins/spaces/common/lib/spaces_url_parser.ts", - "lineNumber": 12 + "lineNumber": 21 }, "initialIsOpen": false }, @@ -1346,32 +1855,42 @@ "id": "def-common.GetAllSpacesOptions", "type": "Interface", "label": "GetAllSpacesOptions", - "description": [], + "description": [ + "\nControls how spaces are retrieved." + ], "tags": [], "children": [ { - "tags": [], + "tags": [ + "see" + ], "id": "def-common.GetAllSpacesOptions.purpose", "type": "CompoundType", "label": "purpose", - "description": [], + "description": [ + "\nAn optional purpose describing how the set of spaces will be used.\nThe default purpose (`any`) will retrieve all spaces the user is authorized to see,\nwhereas a more specific purpose will retrieve all spaces the user is authorized to perform a specific action within.\n" + ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 11 + "lineNumber": 21 }, "signature": [ "\"any\" | \"copySavedObjectsIntoSpace\" | \"findSavedObjects\" | \"shareSavedObjectsIntoSpace\" | undefined" ] }, { - "tags": [], + "tags": [ + "see" + ], "id": "def-common.GetAllSpacesOptions.includeAuthorizedPurposes", "type": "CompoundType", "label": "includeAuthorizedPurposes", - "description": [], + "description": [ + "\nSet to true to return a set of flags indicating which purposes the user is authorized for.\n" + ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 12 + "lineNumber": 28 }, "signature": [ "boolean | undefined" @@ -1380,7 +1899,7 @@ ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 10 + "lineNumber": 13 }, "initialIsOpen": false }, @@ -1405,7 +1924,9 @@ "text": "Space" } ], - "description": [], + "description": [ + "\nResponse format when querying for spaces." + ], "tags": [], "children": [ { @@ -1413,10 +1934,12 @@ "id": "def-common.GetSpaceResult.authorizedPurposes", "type": "Object", "label": "authorizedPurposes", - "description": [], + "description": [ + "\nA set of flags indicating which purposes the user is authorized for." + ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 22 + "lineNumber": 51 }, "signature": [ "Record<", @@ -1433,7 +1956,7 @@ ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 21 + "lineNumber": 47 }, "initialIsOpen": false } @@ -1462,10 +1985,12 @@ "type": "Type", "label": "GetAllSpacesPurpose", "tags": [], - "description": [], + "description": [ + "\nThe set of purposes to retrieve spaces:\n- `any`: retrieves all spaces the user is authorized to see.\n- `copySavedObjectsIntoSpace`: retrieves all spaces the user is authorized to copy saved objects into.\n- `findSavedObjects`: retrieves all spaces the user is authorized to search within.\n- `shareSavedObjectsIntoSpace`: retrieves all spaces the user is authorized to share saved objects into." + ], "source": { "path": "x-pack/plugins/spaces/common/types.ts", - "lineNumber": 15 + "lineNumber": 38 }, "signature": [ "\"any\" | \"copySavedObjectsIntoSpace\" | \"findSavedObjects\" | \"shareSavedObjectsIntoSpace\"" diff --git a/api_docs/spaces_oss.json b/api_docs/spaces_oss.json index a93aeefb3db6..8442d6cb5d5b 100644 --- a/api_docs/spaces_oss.json +++ b/api_docs/spaces_oss.json @@ -8,10 +8,10 @@ "id": "def-public.LegacyUrlConflictProps", "type": "Interface", "label": "LegacyUrlConflictProps", - "description": [], - "tags": [ - "public" + "description": [ + "\nProperties for the LegacyUrlConflict component." ], + "tags": [], "children": [ { "tags": [], @@ -23,7 +23,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 252 + "lineNumber": 257 }, "signature": [ "string | undefined" @@ -39,7 +39,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 256 + "lineNumber": 261 } }, { @@ -52,7 +52,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 260 + "lineNumber": 265 } }, { @@ -65,13 +65,13 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 264 + "lineNumber": 269 } } ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 245 + "lineNumber": 250 }, "initialIsOpen": false }, @@ -79,10 +79,10 @@ "id": "def-public.ShareToSpaceFlyoutProps", "type": "Interface", "label": "ShareToSpaceFlyoutProps", - "description": [], - "tags": [ - "public" + "description": [ + "\nProperties for the ShareToSpaceFlyout." ], + "tags": [], "children": [ { "tags": [], @@ -94,7 +94,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 130 + "lineNumber": 135 }, "signature": [ { @@ -116,7 +116,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 136 + "lineNumber": 141 }, "signature": [ "string | undefined" @@ -132,7 +132,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 142 + "lineNumber": 147 }, "signature": [ "string | undefined" @@ -148,7 +148,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 149 + "lineNumber": 154 }, "signature": [ "boolean | undefined" @@ -164,7 +164,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 156 + "lineNumber": 161 }, "signature": [ "boolean | undefined" @@ -180,7 +180,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 164 + "lineNumber": 169 }, "signature": [ "\"within-space\" | \"outside-space\" | undefined" @@ -196,7 +196,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 170 + "lineNumber": 175 }, "signature": [ "((spacesToAdd: string[], spacesToRemove: string[]) => Promise) | undefined" @@ -212,7 +212,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 174 + "lineNumber": 179 }, "signature": [ "(() => void) | undefined" @@ -228,7 +228,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 178 + "lineNumber": 183 }, "signature": [ "(() => void) | undefined" @@ -237,7 +237,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 126 + "lineNumber": 131 }, "initialIsOpen": false }, @@ -245,10 +245,10 @@ "id": "def-public.ShareToSpaceSavedObjectTarget", "type": "Interface", "label": "ShareToSpaceSavedObjectTarget", - "description": [], - "tags": [ - "public" + "description": [ + "\nDescribes the target saved object during a share operation." ], + "tags": [], "children": [ { "tags": [], @@ -260,7 +260,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 188 + "lineNumber": 193 } }, { @@ -273,7 +273,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 192 + "lineNumber": 197 } }, { @@ -286,7 +286,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 196 + "lineNumber": 201 }, "signature": [ "string[]" @@ -302,7 +302,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 202 + "lineNumber": 207 }, "signature": [ "string | undefined" @@ -318,7 +318,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 208 + "lineNumber": 213 }, "signature": [ "string | undefined" @@ -334,7 +334,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 214 + "lineNumber": 219 }, "signature": [ "string | undefined" @@ -343,7 +343,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 184 + "lineNumber": 189 }, "initialIsOpen": false }, @@ -351,20 +351,22 @@ "id": "def-public.SpaceAvatarProps", "type": "Interface", "label": "SpaceAvatarProps", - "description": [], - "tags": [ - "public" + "description": [ + "\nProperties for the SpaceAvatar component." ], + "tags": [], "children": [ { "tags": [], "id": "def-public.SpaceAvatarProps.space", "type": "Object", "label": "space", - "description": [], + "description": [ + "The space to represent with an avatar." + ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 271 + "lineNumber": 277 }, "signature": [ "Partial<", @@ -383,10 +385,12 @@ "id": "def-public.SpaceAvatarProps.size", "type": "CompoundType", "label": "size", - "description": [], + "description": [ + "The size of the avatar." + ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 272 + "lineNumber": 280 }, "signature": [ "\"m\" | \"s\" | \"l\" | \"xl\" | undefined" @@ -397,10 +401,12 @@ "id": "def-public.SpaceAvatarProps.className", "type": "string", "label": "className", - "description": [], + "description": [ + "Optional CSS class(es) to apply." + ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 273 + "lineNumber": 283 }, "signature": [ "string | undefined" @@ -416,7 +422,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 279 + "lineNumber": 290 }, "signature": [ "boolean | undefined" @@ -425,7 +431,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 270 + "lineNumber": 275 }, "initialIsOpen": false }, @@ -433,10 +439,10 @@ "id": "def-public.SpaceListProps", "type": "Interface", "label": "SpaceListProps", - "description": [], - "tags": [ - "public" + "description": [ + "\nProperties for the SpaceList component." ], + "tags": [], "children": [ { "tags": [], @@ -448,7 +454,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 224 + "lineNumber": 229 }, "signature": [ "string[]" @@ -464,7 +470,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 231 + "lineNumber": 236 }, "signature": [ "number | undefined" @@ -480,7 +486,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 239 + "lineNumber": 244 }, "signature": [ "\"within-space\" | \"outside-space\" | undefined" @@ -489,7 +495,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 220 + "lineNumber": 225 }, "initialIsOpen": false }, @@ -497,20 +503,22 @@ "id": "def-public.SpacesApi", "type": "Interface", "label": "SpacesApi", - "description": [], - "tags": [ - "public" + "description": [ + "\nClient-side Spaces API." ], + "tags": [], "children": [ { "tags": [], "id": "def-public.SpacesApi.activeSpace$", "type": "Object", "label": "activeSpace$", - "description": [], + "description": [ + "\nObservable representing the currently active space.\nThe details of the space can change without a full page reload (such as display name, color, etc.)" + ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 18 + "lineNumber": 22 }, "signature": [ "Observable", @@ -540,13 +548,15 @@ }, ">" ], - "description": [], + "description": [ + "\nRetrieve the currently active space." + ], "children": [], "tags": [], "returnComment": [], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 19 + "lineNumber": 27 } }, { @@ -555,11 +565,11 @@ "type": "Object", "label": "ui", "description": [ - "\nUI API to use to add spaces capabilities to an application" + "\nUI components and services to add spaces capabilities to an application." ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 23 + "lineNumber": 32 }, "signature": [ { @@ -582,10 +592,10 @@ "id": "def-public.SpacesApiUi", "type": "Interface", "label": "SpacesApiUi", - "description": [], - "tags": [ - "public" + "description": [ + "\nUI components and services to add spaces capabilities to an application." ], + "tags": [], "children": [ { "tags": [], @@ -593,11 +603,11 @@ "type": "Object", "label": "components", "description": [ - "\nLazy-loadable {@link SpacesApiUiComponent | React components} to support the spaces feature." + "\nLazy-loadable {@link SpacesApiUiComponent | React components} to support the Spaces feature." ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 40 + "lineNumber": 47 }, "signature": [ { @@ -619,7 +629,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 61 + "lineNumber": 68 }, "signature": [ "(path: string, objectNoun?: string | undefined) => Promise" @@ -628,7 +638,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 36 + "lineNumber": 43 }, "initialIsOpen": false }, @@ -637,11 +647,9 @@ "type": "Interface", "label": "SpacesApiUiComponent", "description": [ - "\nReact UI components to be used to display the spaces feature in any application.\n" - ], - "tags": [ - "public" + "\nReact UI components to be used to display the Spaces feature in any application." ], + "tags": [], "children": [ { "tags": [], @@ -653,7 +661,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 73 + "lineNumber": 78 }, "signature": [ { @@ -684,7 +692,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 79 + "lineNumber": 84 }, "signature": [ { @@ -715,7 +723,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 88 + "lineNumber": 93 }, "signature": [ { @@ -746,7 +754,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 106 + "lineNumber": 111 }, "signature": [ { @@ -777,7 +785,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 110 + "lineNumber": 115 }, "signature": [ { @@ -801,7 +809,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 69 + "lineNumber": 74 }, "initialIsOpen": false }, @@ -826,7 +834,9 @@ "text": "SpacesApi" } ], - "description": [], + "description": [ + "\nOSS Spaces plugin start contract when the Spaces feature is enabled." + ], "tags": [], "children": [ { @@ -834,10 +844,12 @@ "id": "def-public.SpacesAvailableStartContract.isSpacesAvailable", "type": "boolean", "label": "isSpacesAvailable", - "description": [], + "description": [ + "Indicates if the Spaces feature is enabled." + ], "source": { "path": "src/plugins/spaces_oss/public/types.ts", - "lineNumber": 12 + "lineNumber": 16 }, "signature": [ "true" @@ -846,7 +858,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/types.ts", - "lineNumber": 11 + "lineNumber": 14 }, "initialIsOpen": false }, @@ -854,10 +866,10 @@ "id": "def-public.SpacesContextProps", "type": "Interface", "label": "SpacesContextProps", - "description": [], - "tags": [ - "public" + "description": [ + "\nProperties for the SpacesContext." ], + "tags": [], "children": [ { "tags": [], @@ -869,7 +881,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 120 + "lineNumber": 125 }, "signature": [ "string | undefined" @@ -878,7 +890,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 116 + "lineNumber": 121 }, "initialIsOpen": false }, @@ -886,18 +898,25 @@ "id": "def-public.SpacesUnavailableStartContract", "type": "Interface", "label": "SpacesUnavailableStartContract", - "description": [], - "tags": [], + "description": [ + "\nOSS Spaces plugin start contract when the Spaces feature is disabled." + ], + "tags": [ + "deprecated", + "removeBy" + ], "children": [ { "tags": [], "id": "def-public.SpacesUnavailableStartContract.isSpacesAvailable", "type": "boolean", "label": "isSpacesAvailable", - "description": [], + "description": [ + "Indicates if the Spaces feature is enabled." + ], "source": { "path": "src/plugins/spaces_oss/public/types.ts", - "lineNumber": 16 + "lineNumber": 26 }, "signature": [ "false" @@ -906,7 +925,7 @@ ], "source": { "path": "src/plugins/spaces_oss/public/types.ts", - "lineNumber": 15 + "lineNumber": 24 }, "initialIsOpen": false } @@ -917,15 +936,13 @@ "id": "def-public.LazyComponentFn", "type": "Type", "label": "LazyComponentFn", - "tags": [ - "public" - ], + "tags": [], "description": [ - "\nFunction that returns a promise for a lazy-loadable component.\n" + "\nFunction that returns a promise for a lazy-loadable component." ], "source": { "path": "src/plugins/spaces_oss/public/api.ts", - "lineNumber": 31 + "lineNumber": 38 }, "signature": [ "(props: T) => React.ReactElement React.ReactElement React.Component)> | null) | (new (props: any) => React.Component)>" @@ -938,7 +955,9 @@ "id": "def-public.SpacesOssPluginSetup", "type": "Interface", "label": "SpacesOssPluginSetup", - "description": [], + "description": [ + "\nOSS Spaces plugin setup contract." + ], "tags": [], "children": [ { @@ -957,7 +976,7 @@ ") => void" ], "description": [ - "\nRegister a provider for the Spaces API.\n\nOnly one provider can be registered, subsequent calls to this method will fail." + "\nRegister a provider for the Spaces API.\n\nOnly one provider can be registered, subsequent calls to this method will fail.\n" ], "children": [ { @@ -974,24 +993,28 @@ "text": "SpacesApi" } ], - "description": [], + "description": [ + "the API provider." + ], "source": { "path": "src/plugins/spaces_oss/public/types.ts", - "lineNumber": 25 + "lineNumber": 42 } } ], - "tags": [], + "tags": [ + "private" + ], "returnComment": [], "source": { "path": "src/plugins/spaces_oss/public/types.ts", - "lineNumber": 25 + "lineNumber": 42 } } ], "source": { "path": "src/plugins/spaces_oss/public/types.ts", - "lineNumber": 19 + "lineNumber": 32 }, "lifecycle": "setup", "initialIsOpen": true @@ -1001,10 +1024,12 @@ "type": "Type", "label": "SpacesOssPluginStart", "tags": [], - "description": [], + "description": [ + "\nOSS Spaces plugin start contract." + ], "source": { "path": "src/plugins/spaces_oss/public/types.ts", - "lineNumber": 28 + "lineNumber": 48 }, "signature": [ { @@ -1043,7 +1068,9 @@ "id": "def-common.Space", "type": "Interface", "label": "Space", - "description": [], + "description": [ + "\nA Kibana Space." + ], "tags": [], "children": [ { @@ -1051,10 +1078,12 @@ "id": "def-common.Space.id", "type": "string", "label": "id", - "description": [], + "description": [ + "\nThe unique identifier for this space.\nThe id becomes part of the \"URL Identifier\" of the space.\n\nExample: an id of `marketing` would result in the URL identifier of `/s/marketing`." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 10 + "lineNumber": 19 } }, { @@ -1062,10 +1091,12 @@ "id": "def-common.Space.name", "type": "string", "label": "name", - "description": [], + "description": [ + "\nDisplay name for this space." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 11 + "lineNumber": 24 } }, { @@ -1073,10 +1104,12 @@ "id": "def-common.Space.description", "type": "string", "label": "description", - "description": [], + "description": [ + "\nOptional description for this space." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 12 + "lineNumber": 29 }, "signature": [ "string | undefined" @@ -1087,10 +1120,12 @@ "id": "def-common.Space.color", "type": "string", "label": "color", - "description": [], + "description": [ + "\nOptional color (hex code) for this space.\nIf neither `color` nor `imageUrl` is specified, then a color will be automatically generated." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 13 + "lineNumber": 35 }, "signature": [ "string | undefined" @@ -1101,10 +1136,28 @@ "id": "def-common.Space.initials", "type": "string", "label": "initials", - "description": [], + "description": [ + "\nOptional display initials for this space's avatar. Supports a maximum of 2 characters.\nIf initials are not provided, then they will be derived from the space name automatically.\n\nInitials are not displayed if an `imageUrl` has been specified." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 14 + "lineNumber": 43 + }, + "signature": [ + "string | undefined" + ] + }, + { + "tags": [], + "id": "def-common.Space.imageUrl", + "type": "string", + "label": "imageUrl", + "description": [ + "\nOptional base-64 encoded data image url to show as this space's avatar.\nThis setting takes precedence over any configured `color` or `initials`." + ], + "source": { + "path": "src/plugins/spaces_oss/common/types.ts", + "lineNumber": 49 }, "signature": [ "string | undefined" @@ -1115,47 +1168,39 @@ "id": "def-common.Space.disabledFeatures", "type": "Array", "label": "disabledFeatures", - "description": [], + "description": [ + "\nThe set of feature ids that should be hidden within this space." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 15 + "lineNumber": 54 }, "signature": [ "string[]" ] }, { - "tags": [], + "tags": [ + "private" + ], "id": "def-common.Space._reserved", "type": "CompoundType", "label": "_reserved", - "description": [], + "description": [ + "\nIndicates that this space is reserved (system controlled).\nReserved spaces cannot be created or deleted by end-users." + ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 16 + "lineNumber": 61 }, "signature": [ "boolean | undefined" ] - }, - { - "tags": [], - "id": "def-common.Space.imageUrl", - "type": "string", - "label": "imageUrl", - "description": [], - "source": { - "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 17 - }, - "signature": [ - "string | undefined" - ] } ], "source": { "path": "src/plugins/spaces_oss/common/types.ts", - "lineNumber": 9 + "lineNumber": 12 }, "initialIsOpen": false } diff --git a/src/plugins/spaces_oss/common/types.ts b/src/plugins/spaces_oss/common/types.ts index a7e2257dd424..b5c418cf3177 100644 --- a/src/plugins/spaces_oss/common/types.ts +++ b/src/plugins/spaces_oss/common/types.ts @@ -6,13 +6,57 @@ * Side Public License, v 1. */ +/** + * A Space. + */ export interface Space { + /** + * The unique identifier for this space. + * The id becomes part of the "URL Identifier" of the space. + * + * Example: an id of `marketing` would result in the URL identifier of `/s/marketing`. + */ id: string; + + /** + * Display name for this space. + */ name: string; + + /** + * Optional description for this space. + */ description?: string; + + /** + * Optional color (hex code) for this space. + * If neither `color` nor `imageUrl` is specified, then a color will be automatically generated. + */ color?: string; + + /** + * Optional display initials for this space's avatar. Supports a maximum of 2 characters. + * If initials are not provided, then they will be derived from the space name automatically. + * + * Initials are not displayed if an `imageUrl` has been specified. + */ initials?: string; - disabledFeatures: string[]; - _reserved?: boolean; + + /** + * Optional base-64 encoded data image url to show as this space's avatar. + * This setting takes precedence over any configured `color` or `initials`. + */ imageUrl?: string; + + /** + * The set of feature ids that should be hidden within this space. + */ + disabledFeatures: string[]; + + /** + * Indicates that this space is reserved (system controlled). + * Reserved spaces cannot be created or deleted by end-users. + * @private + */ + _reserved?: boolean; } diff --git a/src/plugins/spaces_oss/public/api.ts b/src/plugins/spaces_oss/public/api.ts index 3f562bcbed8e..bd452c2fca00 100644 --- a/src/plugins/spaces_oss/public/api.ts +++ b/src/plugins/spaces_oss/public/api.ts @@ -12,30 +12,37 @@ import type { Observable } from 'rxjs'; import type { Space } from '../common'; /** - * @public + * Client-side Spaces API. */ export interface SpacesApi { - readonly activeSpace$: Observable; - getActiveSpace(): Promise; /** - * UI API to use to add spaces capabilities to an application + * Observable representing the currently active space. + * The details of the space can change without a full page reload (such as display name, color, etc.) + */ + readonly activeSpace$: Observable; + + /** + * Retrieve the currently active space. + */ + getActiveSpace(): Promise; + + /** + * UI components and services to add spaces capabilities to an application. */ ui: SpacesApiUi; } /** * Function that returns a promise for a lazy-loadable component. - * - * @public */ export type LazyComponentFn = (props: T) => ReactElement; /** - * @public + * UI components and services to add spaces capabilities to an application. */ export interface SpacesApiUi { /** - * Lazy-loadable {@link SpacesApiUiComponent | React components} to support the spaces feature. + * Lazy-loadable {@link SpacesApiUiComponent | React components} to support the Spaces feature. */ components: SpacesApiUiComponent; /** @@ -62,9 +69,7 @@ export interface SpacesApiUi { } /** - * React UI components to be used to display the spaces feature in any application. - * - * @public + * React UI components to be used to display the Spaces feature in any application. */ export interface SpacesApiUiComponent { /** @@ -111,7 +116,7 @@ export interface SpacesApiUiComponent { } /** - * @public + * Properties for the SpacesContext. */ export interface SpacesContextProps { /** @@ -121,7 +126,7 @@ export interface SpacesContextProps { } /** - * @public + * Properties for the ShareToSpaceFlyout. */ export interface ShareToSpaceFlyoutProps { /** @@ -179,7 +184,7 @@ export interface ShareToSpaceFlyoutProps { } /** - * @public + * Describes the target saved object during a share operation. */ export interface ShareToSpaceSavedObjectTarget { /** @@ -215,7 +220,7 @@ export interface ShareToSpaceSavedObjectTarget { } /** - * @public + * Properties for the SpaceList component. */ export interface SpaceListProps { /** @@ -240,7 +245,7 @@ export interface SpaceListProps { } /** - * @public + * Properties for the LegacyUrlConflict component. */ export interface LegacyUrlConflictProps { /** @@ -265,12 +270,18 @@ export interface LegacyUrlConflictProps { } /** - * @public + * Properties for the SpaceAvatar component. */ export interface SpaceAvatarProps { + /** The space to represent with an avatar. */ space: Partial; + + /** The size of the avatar. */ size?: 's' | 'm' | 'l' | 'xl'; + + /** Optional CSS class(es) to apply. */ className?: string; + /** * When enabled, allows EUI to provide an aria-label for this component, which is announced on screen readers. * diff --git a/src/plugins/spaces_oss/public/index.ts b/src/plugins/spaces_oss/public/index.ts index 828ce6f4dec6..9c4d5fd17700 100644 --- a/src/plugins/spaces_oss/public/index.ts +++ b/src/plugins/spaces_oss/public/index.ts @@ -8,14 +8,14 @@ import { SpacesOssPlugin } from './plugin'; -export { +export type { SpacesOssPluginSetup, SpacesOssPluginStart, SpacesAvailableStartContract, SpacesUnavailableStartContract, } from './types'; -export { +export type { LazyComponentFn, SpacesApi, SpacesApiUi, diff --git a/src/plugins/spaces_oss/public/types.ts b/src/plugins/spaces_oss/public/types.ts index 22501d3abd83..df20e9be6eaa 100644 --- a/src/plugins/spaces_oss/public/types.ts +++ b/src/plugins/spaces_oss/public/types.ts @@ -8,21 +8,41 @@ import type { SpacesApi } from './api'; +/** + * OSS Spaces plugin start contract when the Spaces feature is enabled. + */ export interface SpacesAvailableStartContract extends SpacesApi { + /** Indicates if the Spaces feature is enabled. */ isSpacesAvailable: true; } +/** + * OSS Spaces plugin start contract when the Spaces feature is disabled. + * @deprecated The Spaces plugin will always be enabled starting in 8.0. + * @removeBy 8.0 + */ export interface SpacesUnavailableStartContract { + /** Indicates if the Spaces feature is enabled. */ isSpacesAvailable: false; } +/** + * OSS Spaces plugin setup contract. + */ export interface SpacesOssPluginSetup { /** * Register a provider for the Spaces API. * * Only one provider can be registered, subsequent calls to this method will fail. + * + * @param provider the API provider. + * + * @private designed to only be consumed by the `spaces` plugin. */ registerSpacesApi(provider: SpacesApi): void; } +/** + * OSS Spaces plugin start contract. + */ export type SpacesOssPluginStart = SpacesAvailableStartContract | SpacesUnavailableStartContract; diff --git a/x-pack/plugins/enterprise_search/server/lib/check_access.test.ts b/x-pack/plugins/enterprise_search/server/lib/check_access.test.ts index 3c5d33fa74d3..ed105eed9dd6 100644 --- a/x-pack/plugins/enterprise_search/server/lib/check_access.test.ts +++ b/x-pack/plugins/enterprise_search/server/lib/check_access.test.ts @@ -62,7 +62,7 @@ describe('checkAccess', () => { }); }); - describe('when the spaces plugin is unavailable', () => { + describe('when the Spaces plugin is unavailable', () => { describe('when security is disabled', () => { it('should allow all access', async () => { const spaces = undefined; diff --git a/x-pack/plugins/spaces/common/lib/spaces_url_parser.ts b/x-pack/plugins/spaces/common/lib/spaces_url_parser.ts index e607936be274..9b24a7079203 100644 --- a/x-pack/plugins/spaces/common/lib/spaces_url_parser.ts +++ b/x-pack/plugins/spaces/common/lib/spaces_url_parser.ts @@ -9,6 +9,15 @@ import { DEFAULT_SPACE_ID } from '../constants'; const spaceContextRegex = /^\/s\/([a-z0-9_\-]+)/; +/** + * Extracts the space id from the given path. + * + * @param requestBasePath The base path of the current request. + * @param serverBasePath The server's base path. + * @returns the space id. + * + * @private + */ export function getSpaceIdFromPath( requestBasePath?: string | null, serverBasePath?: string | null @@ -40,6 +49,15 @@ export function getSpaceIdFromPath( }; } +/** + * Given a server base path, space id, and requested resource, this will construct a space-aware path + * that includes a URL identifier with the space id. + * + * @param basePath the server's base path. + * @param spaceId the space id. + * @param requestedPath the requested path (e.g. `/app/dashboard`). + * @returns the space-aware version of the requested path, inclusive of the server's base path. + */ export function addSpaceIdToPath( basePath: string = '/', spaceId: string = '', diff --git a/x-pack/plugins/spaces/common/types.ts b/x-pack/plugins/spaces/common/types.ts index 46455c1f601d..866d29bf64d5 100644 --- a/x-pack/plugins/spaces/common/types.ts +++ b/x-pack/plugins/spaces/common/types.ts @@ -7,17 +7,46 @@ import type { Space } from 'src/plugins/spaces_oss/common'; +/** + * Controls how spaces are retrieved. + */ export interface GetAllSpacesOptions { + /** + * An optional purpose describing how the set of spaces will be used. + * The default purpose (`any`) will retrieve all spaces the user is authorized to see, + * whereas a more specific purpose will retrieve all spaces the user is authorized to perform a specific action within. + * + * @see GetAllSpacesPurpose + */ purpose?: GetAllSpacesPurpose; + + /** + * Set to true to return a set of flags indicating which purposes the user is authorized for. + * + * @see GetAllSpacesPurpose + */ includeAuthorizedPurposes?: boolean; } +/** + * The set of purposes to retrieve spaces: + * - `any`: retrieves all spaces the user is authorized to see. + * - `copySavedObjectsIntoSpace`: retrieves all spaces the user is authorized to copy saved objects into. + * - `findSavedObjects`: retrieves all spaces the user is authorized to search within. + * - `shareSavedObjectsIntoSpace`: retrieves all spaces the user is authorized to share saved objects into. + */ export type GetAllSpacesPurpose = | 'any' | 'copySavedObjectsIntoSpace' | 'findSavedObjects' | 'shareSavedObjectsIntoSpace'; +/** + * Response format when querying for spaces. + */ export interface GetSpaceResult extends Space { + /** + * A set of flags indicating which purposes the user is authorized for. + */ authorizedPurposes?: Record; } diff --git a/x-pack/plugins/spaces/public/plugin.tsx b/x-pack/plugins/spaces/public/plugin.tsx index 062a534c91c8..889267155189 100644 --- a/x-pack/plugins/spaces/public/plugin.tsx +++ b/x-pack/plugins/spaces/public/plugin.tsx @@ -36,7 +36,14 @@ export interface PluginsStart { management?: ManagementStart; } +/** + * Setup contract for the Spaces plugin. + */ export type SpacesPluginSetup = ReturnType; + +/** + * Start contract for the Spaces plugin. + */ export type SpacesPluginStart = ReturnType; export class SpacesPlugin implements Plugin { diff --git a/x-pack/plugins/spaces/public/space_avatar/space_attributes.ts b/x-pack/plugins/spaces/public/space_avatar/space_attributes.ts index e37d7eed322e..682a61c6f23a 100644 --- a/x-pack/plugins/spaces/public/space_avatar/space_attributes.ts +++ b/x-pack/plugins/spaces/public/space_avatar/space_attributes.ts @@ -19,7 +19,7 @@ const FALLBACK_CODE_POINT = 97; * If a color is present on the Space itself, then that is used. * Otherwise, a color is provided from EUI's Visualization Colors based on the space name. * - * @param {Space} space + * @param {Space} space the space. */ export function getSpaceColor(space: Partial = {}) { const { color, name = '' } = space; @@ -38,7 +38,7 @@ export function getSpaceColor(space: Partial = {}) { * If initials are present on the Space itself, then that is used. * Otherwise, the initials are calculated based off the words in the space name, with a max length of 2 characters. * - * @param {Space} space + * @param {Space} space the space. */ export function getSpaceInitials(space: Partial = {}) { const { initials, name = '' } = space; @@ -59,7 +59,7 @@ export function getSpaceInitials(space: Partial = {}) { /** * Determines the avatar image for the provided space. * - * @param {Space} space + * @param {Space} space the space. */ export function getSpaceImageUrl(space: Partial = {}) { const { imageUrl } = space; diff --git a/x-pack/plugins/spaces/server/config.test.ts b/x-pack/plugins/spaces/server/config.test.ts index 1ce1be0698b1..1e60c1b63532 100644 --- a/x-pack/plugins/spaces/server/config.test.ts +++ b/x-pack/plugins/spaces/server/config.test.ts @@ -37,7 +37,7 @@ describe('spaces config', () => { expect(messages).toMatchInlineSnapshot(` Array [ - "Disabling the spaces plugin (xpack.spaces.enabled) will not be supported in the next major version (8.0)", + "Disabling the Spaces plugin (xpack.spaces.enabled) will not be supported in the next major version (8.0)", ] `); expect(migrated).toEqual(originalConfig); diff --git a/x-pack/plugins/spaces/server/config.ts b/x-pack/plugins/spaces/server/config.ts index ed541fda6c29..7f8b1a29befb 100644 --- a/x-pack/plugins/spaces/server/config.ts +++ b/x-pack/plugins/spaces/server/config.ts @@ -27,7 +27,7 @@ export function createConfig$(context: PluginInitializerContext) { const disabledDeprecation: ConfigDeprecation = (config, fromPath, addDeprecation) => { if (config.xpack?.spaces?.enabled === false) { addDeprecation({ - message: `Disabling the spaces plugin (xpack.spaces.enabled) will not be supported in the next major version (8.0)`, + message: `Disabling the Spaces plugin (xpack.spaces.enabled) will not be supported in the next major version (8.0)`, }); } return config; diff --git a/x-pack/plugins/spaces/server/index.ts b/x-pack/plugins/spaces/server/index.ts index 4218d8518720..c779e92a3ae9 100644 --- a/x-pack/plugins/spaces/server/index.ts +++ b/x-pack/plugins/spaces/server/index.ts @@ -21,7 +21,7 @@ export { addSpaceIdToPath } from '../common'; export { SpacesPluginSetup, SpacesPluginStart } from './plugin'; export { SpacesServiceSetup, SpacesServiceStart } from './spaces_service'; -export { ISpacesClient } from './spaces_client'; +export { ISpacesClient, SpacesClientRepositoryFactory, SpacesClientWrapper } from './spaces_client'; export { GetAllSpacesOptions, GetAllSpacesPurpose, GetSpaceResult } from '../common'; diff --git a/x-pack/plugins/spaces/server/plugin.test.ts b/x-pack/plugins/spaces/server/plugin.test.ts index 94236b6e7f58..c5732fc4045b 100644 --- a/x-pack/plugins/spaces/server/plugin.test.ts +++ b/x-pack/plugins/spaces/server/plugin.test.ts @@ -14,7 +14,7 @@ import { licensingMock } from '../../licensing/server/mocks'; import type { PluginsStart } from './plugin'; import { SpacesPlugin } from './plugin'; -describe('Spaces Plugin', () => { +describe('Spaces plugin', () => { describe('#setup', () => { it('can setup with all optional plugins disabled, exposing the expected contract', () => { const initializerContext = coreMock.createPluginInitializerContext({}); diff --git a/x-pack/plugins/spaces/server/plugin.ts b/x-pack/plugins/spaces/server/plugin.ts index aaa19ee74cb7..a7400fb71c1d 100644 --- a/x-pack/plugins/spaces/server/plugin.ts +++ b/x-pack/plugins/spaces/server/plugin.ts @@ -51,15 +51,41 @@ export interface PluginsStart { features: FeaturesPluginStart; } +/** + * Setup contract for the Spaces plugin. + */ export interface SpacesPluginSetup { + /** + * Service for interacting with spaces. + * + * @deprecated Please use the `spacesService` available on this plugin's start contract. + * @removeBy 7.16 + */ spacesService: SpacesServiceSetup; + + /** + * Registries exposed for the security plugin to transparently provide authorization and audit logging. + * @private + */ spacesClient: { + /** + * Sets the client repository factory. + * @private + */ setClientRepositoryFactory: (factory: SpacesClientRepositoryFactory) => void; + /** + * Registers a client wrapper. + * @private + */ registerClientWrapper: (wrapper: SpacesClientWrapper) => void; }; } +/** + * Start contract for the Spaces plugin. + */ export interface SpacesPluginStart { + /** Service for interacting with spaces. */ spacesService: SpacesServiceStart; } diff --git a/x-pack/plugins/spaces/server/spaces_client/spaces_client.ts b/x-pack/plugins/spaces/server/spaces_client/spaces_client.ts index c4f5e9edaf49..02aa4d0b976c 100644 --- a/x-pack/plugins/spaces/server/spaces_client/spaces_client.ts +++ b/x-pack/plugins/spaces/server/spaces_client/spaces_client.ts @@ -8,7 +8,6 @@ import Boom from '@hapi/boom'; import { omit } from 'lodash'; -import type { PublicMethodsOf } from '@kbn/utility-types'; import type { ISavedObjectsRepository, SavedObject } from 'src/core/server'; import type { Space } from 'src/plugins/spaces_oss/common'; @@ -24,9 +23,46 @@ const SUPPORTED_GET_SPACE_PURPOSES: GetAllSpacesPurpose[] = [ ]; const DEFAULT_PURPOSE = 'any'; -export type ISpacesClient = PublicMethodsOf; +/** + * Client interface for interacting with spaces. + */ +export interface ISpacesClient { + /** + * Retrieve all available spaces. + * @param options controls which spaces are retrieved. + */ + getAll(options?: GetAllSpacesOptions): Promise; -export class SpacesClient { + /** + * Retrieve a space by its id. + * @param id the space id. + */ + get(id: string): Promise; + + /** + * Creates a space. + * @param space the space to create. + */ + create(space: Space): Promise; + + /** + * Updates a space. + * @param id the id of the space to update. + * @param space the updated space. + */ + update(id: string, space: Space): Promise; + + /** + * Deletes a space, and all saved objects belonging to that space. + * @param id the id of the space to delete. + */ + delete(id: string): Promise; +} + +/** + * Client for interacting with spaces. + */ +export class SpacesClient implements ISpacesClient { constructor( private readonly debugLogger: (message: string) => void, private readonly config: ConfigType, diff --git a/x-pack/plugins/spaces/server/spaces_client/spaces_client_service.ts b/x-pack/plugins/spaces/server/spaces_client/spaces_client_service.ts index 4db27bac845f..6580a2d57f04 100644 --- a/x-pack/plugins/spaces/server/spaces_client/spaces_client_service.ts +++ b/x-pack/plugins/spaces/server/spaces_client/spaces_client_service.ts @@ -18,11 +18,19 @@ import type { ConfigType } from '../config'; import type { ISpacesClient } from './spaces_client'; import { SpacesClient } from './spaces_client'; +/** + * For consumption by the security plugin only. + * @private + */ export type SpacesClientWrapper = ( request: KibanaRequest, baseClient: ISpacesClient ) => ISpacesClient; +/** + * For consumption by the security plugin only. + * @private + */ export type SpacesClientRepositoryFactory = ( request: KibanaRequest, savedObjectsStart: SavedObjectsServiceStart diff --git a/x-pack/plugins/spaces/server/spaces_service/spaces_service.ts b/x-pack/plugins/spaces/server/spaces_service/spaces_service.ts index c76646fa8a2b..e951ed38072d 100644 --- a/x-pack/plugins/spaces/server/spaces_service/spaces_service.ts +++ b/x-pack/plugins/spaces/server/spaces_service/spaces_service.ts @@ -11,67 +11,77 @@ import type { Space } from 'src/plugins/spaces_oss/common'; import { getSpaceIdFromPath } from '../../common'; import { DEFAULT_SPACE_ID } from '../../common/constants'; import { namespaceToSpaceId, spaceIdToNamespace } from '../lib/utils/namespace'; -import type { SpacesClientServiceStart } from '../spaces_client'; +import type { ISpacesClient, SpacesClientServiceStart } from '../spaces_client'; +/** + * The Spaces service setup contract. + */ export interface SpacesServiceSetup { /** * Retrieves the space id associated with the provided request. - * @param request + * @param request the request. * * @deprecated Use `getSpaceId` from the `SpacesServiceStart` contract instead. + * @removeBy 7.16 */ getSpaceId(request: KibanaRequest): string; /** * Converts the provided space id into the corresponding Saved Objects `namespace` id. - * @param spaceId + * @param spaceId the space id to convert. * * @deprecated use `spaceIdToNamespace` from the `SpacesServiceStart` contract instead. + * @removeBy 7.16 */ spaceIdToNamespace(spaceId: string): string | undefined; /** * Converts the provided namespace into the corresponding space id. - * @param namespace + * @param namespace the namespace to convert. * * @deprecated use `namespaceToSpaceId` from the `SpacesServiceStart` contract instead. + * @removeBy 7.16 */ namespaceToSpaceId(namespace: string | undefined): string; } +/** + * The Spaces service start contract. + */ export interface SpacesServiceStart { /** * Creates a scoped instance of the SpacesClient. + * @param request the request. */ - createSpacesClient: SpacesClientServiceStart['createSpacesClient']; + createSpacesClient: (request: KibanaRequest) => ISpacesClient; /** * Retrieves the space id associated with the provided request. - * @param request + * @param request the request. */ getSpaceId(request: KibanaRequest): string; /** * Indicates if the provided request is executing within the context of the `default` space. - * @param request + * @param request the request. */ isInDefaultSpace(request: KibanaRequest): boolean; /** * Retrieves the Space associated with the provided request. - * @param request + * @param request the request. */ getActiveSpace(request: KibanaRequest): Promise; /** * Converts the provided space id into the corresponding Saved Objects `namespace` id. - * @param spaceId + * @param spaceId the space id to convert. */ spaceIdToNamespace(spaceId: string): string | undefined; /** * Converts the provided namespace into the corresponding space id. - * @param namespace + * @param namespace the namespace to convert. */ namespaceToSpaceId(namespace: string | undefined): string; } @@ -85,6 +95,9 @@ interface SpacesServiceStartDeps { spacesClientService: SpacesClientServiceStart; } +/** + * Service for interacting with spaces. + */ export class SpacesService { public setup({ basePath }: SpacesServiceSetupDeps): SpacesServiceSetup { return { @@ -96,7 +109,7 @@ export class SpacesService { }; } - public start({ basePath, spacesClientService }: SpacesServiceStartDeps) { + public start({ basePath, spacesClientService }: SpacesServiceStartDeps): SpacesServiceStart { return { getSpaceId: (request: KibanaRequest) => { return this.getSpaceId(request, basePath); diff --git a/x-pack/plugins/spaces/server/usage_collection/spaces_usage_collector.ts b/x-pack/plugins/spaces/server/usage_collection/spaces_usage_collector.ts index ef001edd429f..a43171fc3b46 100644 --- a/x-pack/plugins/spaces/server/usage_collection/spaces_usage_collector.ts +++ b/x-pack/plugins/spaces/server/usage_collection/spaces_usage_collector.ts @@ -338,13 +338,13 @@ export function getSpacesUsageCollector( available: { type: 'boolean', _meta: { - description: 'Indicates if the spaces feature is available in this installation.', + description: 'Indicates if the Spaces feature is available in this installation.', }, }, enabled: { type: 'boolean', _meta: { - description: 'Indicates if the spaces feature is enabled in this installation.', + description: 'Indicates if the Spaces feature is enabled in this installation.', }, }, count: { diff --git a/x-pack/plugins/telemetry_collection_xpack/schema/xpack_plugins.json b/x-pack/plugins/telemetry_collection_xpack/schema/xpack_plugins.json index d2fbbf147efd..43f812edd8cd 100644 --- a/x-pack/plugins/telemetry_collection_xpack/schema/xpack_plugins.json +++ b/x-pack/plugins/telemetry_collection_xpack/schema/xpack_plugins.json @@ -5218,13 +5218,13 @@ "available": { "type": "boolean", "_meta": { - "description": "Indicates if the spaces feature is available in this installation." + "description": "Indicates if the Spaces feature is available in this installation." } }, "enabled": { "type": "boolean", "_meta": { - "description": "Indicates if the spaces feature is enabled in this installation." + "description": "Indicates if the Spaces feature is enabled in this installation." } }, "count": { diff --git a/x-pack/plugins/upgrade_assistant/tests_client_integration/overview.test.ts b/x-pack/plugins/upgrade_assistant/tests_client_integration/overview.test.ts index 33d7177cf15f..fd7cd2c90e95 100644 --- a/x-pack/plugins/upgrade_assistant/tests_client_integration/overview.test.ts +++ b/x-pack/plugins/upgrade_assistant/tests_client_integration/overview.test.ts @@ -49,7 +49,7 @@ describe('Overview page', () => { domainId: 'xpack.spaces', level: 'critical', message: - 'Disabling the spaces plugin (xpack.spaces.enabled) will not be supported in the next major version (8.0)', + 'Disabling the Spaces plugin (xpack.spaces.enabled) will not be supported in the next major version (8.0)', }, ];