[Cases] Cleaning up the services and TODOs

x-pack/plugins/cases/README.md

@@ -14,13 +14,17 @@ Case management in Kibana
 ## Table of Contents
 
 - [Cases API](#cases-api)
+- [Cases Client API](#cases-client-api)
 - [Cases UI](#cases-ui)
 - [Case Action Type](#case-action-type) _feature in development, disabled by default_
 
 
 ## Cases API
 [**Explore the API docs »**](https://www.elastic.co/guide/en/security/current/cases-api-overview.html)
 
+## Cases Client API
+[**Cases Client API docs**][cases-client-api-docs]
+
 ## Cases UI
 
 #### Embed Cases UI components in any Kibana plugin
@@ -263,4 +267,4 @@ For IBM Resilient connectors:
 [all-cases-modal-img]: images/all_cases_selector_modal.png
 [recent-cases-img]: images/recent_cases.png
 [case-view-img]: images/case_view.png
-
+[cases-client-api-docs]: docs/cases_client/cases_client_api.md

x-pack/plugins/cases/common/api/cases/case.ts

@@ -31,13 +31,37 @@ const SettingsRt = rt.type({
 });
 
 const CaseBasicRt = rt.type({
+  /**
+   * The description of the case
+   */
   description: rt.string,
+  /**
+   * The current status of the case (open, closed, in-progress)
+   */
   status: CaseStatusRt,
+  /**
+   * The identifying strings for filter a case
+   */
   tags: rt.array(rt.string),
+  /**
+   * The title of a case
+   */
   title: rt.string,
+  /**
+   * The type of a case (individual or collection)
+   */
   [caseTypeField]: CaseTypeRt,
+  /**
+   * The external system that the case can be synced with
+   */
   connector: CaseConnectorRt,
+  /**
+   * The alert sync settings
+   */
   settings: SettingsRt,
+  /**
+   * The plugin owner of the case
+   */
   owner: rt.string,
 });
 
@@ -74,11 +98,30 @@ export const CaseAttributesRt = rt.intersection([
 ]);
 
 const CasePostRequestNoTypeRt = rt.type({
+  /**
+   * Description of the case
+   */
   description: rt.string,
+  /**
+   * Identifiers for the case.
+   */
   tags: rt.array(rt.string),
+  /**
+   * Title of the case
+   */
   title: rt.string,
+  /**
+   * The external configuration for the case
+   */
   connector: CaseConnectorRt,
+  /**
+   * Sync settings for alerts
+   */
   settings: SettingsRt,
+  /**
+   * The owner here must match the string used when a plugin registers a feature with access to the cases plugin. The user
+   * creating this case must also be granted access to that plugin's feature.
+   */
   owner: rt.string,
 });
 
@@ -97,27 +140,77 @@ export const CasesClientPostRequestRt = rt.type({
  * has all the necessary fields. CasesClientPostRequestRt is used for validation.
  */
 export const CasePostRequestRt = rt.intersection([
+  /**
+   * The case type: an individual case (one without children) or a collection case (one with children)
+   */
   rt.partial({ [caseTypeField]: CaseTypeRt }),
   CasePostRequestNoTypeRt,
 ]);
 
 export const CasesFindRequestRt = rt.partial({
+  /**
+   * Type of a case (individual, or collection)
+   */
   type: CaseTypeRt,
+  /**
+   * Tags to filter by
+   */
   tags: rt.union([rt.array(rt.string), rt.string]),
+  /**
+   * The status of the case (open, closed, in-progress)
+   */
   status: CaseStatusRt,
+  /**
+   * The reporters to filter by
+   */
   reporters: rt.union([rt.array(rt.string), rt.string]),
+  /**
+   * Operator to use for the `search` field
+   */
   defaultSearchOperator: rt.union([rt.literal('AND'), rt.literal('OR')]),
+  /**
+   * The fields in the entity to return in the response
+   */
   fields: rt.array(rt.string),
+  /**
+   * The page of objects to return
+   */
   page: NumberFromString,
+  /**
+   * The number of objects to include in each page
+   */
   perPage: NumberFromString,
+  /**
+   * An Elasticsearch simple_query_string
+   */
   search: rt.string,
+  /**
+   * The fields to perform the simple_query_string parsed query against
+   */
   searchFields: rt.union([rt.array(rt.string), rt.string]),
+  /**
+   * The field to use for sorting the found objects.
+   *
+   * This only supports, `create_at`, `closed_at`, and `status`
+   */
   sortField: rt.string,
+  /**
+   * The order to sort by
+   */
   sortOrder: rt.union([rt.literal('desc'), rt.literal('asc')]),
+  /**
+   * The owner(s) to filter by. The user making the request must have privileges to retrieve cases of that
+   * ownership or they will be ignored. If no owner is included, then all ownership types will be included in the response
+   * that the user has access to.
+   */
   owner: rt.union([rt.array(rt.string), rt.string]),
 });
 
 export const CasesByAlertIDRequestRt = rt.partial({
+  /**
+   * The type of cases to retrieve given an alert ID. If no owner is provided, all cases
+   * that the user has access to will be returned.
+   */
   owner: rt.union([rt.array(rt.string), rt.string]),
 });
 
@@ -148,6 +241,9 @@ export const CasesFindResponseRt = rt.intersection([
 
 export const CasePatchRequestRt = rt.intersection([
   rt.partial(CaseBasicRt.props),
+  /**
+   * The saved object ID and version
+   */
   rt.type({ id: rt.string, version: rt.string }),
 ]);
 
@@ -180,6 +276,10 @@ export const ExternalServiceResponseRt = rt.intersection([
 ]);
 
 export const AllTagsFindRequestRt = rt.partial({
+  /**
+   * The owner of the cases to retrieve the tags from. If no owner is provided the tags from all cases
+   * that the user has access to will be returned.
+   */
   owner: rt.union([rt.array(rt.string), rt.string]),
 });
 

x-pack/plugins/cases/common/api/cases/comment.ts

@@ -133,6 +133,9 @@ export const AllCommentsResponseRt = rt.array(CommentResponseRt);
 
 export const FindQueryParamsRt = rt.partial({
   ...SavedObjectFindOptionsRt.props,
+  /**
+   * If specified the attachments found will be associated to a sub case instead of a case object
+   */
   subCaseId: rt.string,
 });
 

x-pack/plugins/cases/common/api/cases/configure.ts

@@ -16,8 +16,17 @@ import { OWNER_FIELD } from './constants';
 const ClosureTypeRT = rt.union([rt.literal('close-by-user'), rt.literal('close-by-pushing')]);
 
 const CasesConfigureBasicRt = rt.type({
+  /**
+   * The external connector
+   */
   connector: CaseConnectorRt,
+  /**
+   * Whether to close the case after it has been synced with the external system
+   */
   closure_type: ClosureTypeRT,
+  /**
+   * The plugin owner that manages this configuration
+   */
   owner: rt.string,
 });
 
@@ -53,6 +62,10 @@ export const CaseConfigureResponseRt = rt.intersection([
 ]);
 
 export const GetConfigureFindRequestRt = rt.partial({
+  /**
+   * The configuration plugin owner to filter the search by. If this is left empty the results will include all configurations
+   * that the user has permissions to access
+   */
   owner: rt.union([rt.array(rt.string), rt.string]),
 });
 

x-pack/plugins/cases/common/api/cases/sub_case.ts

@@ -14,6 +14,9 @@ import { CasesStatusResponseRt } from './status';
 import { CaseStatusRt } from './status';
 
 const SubCaseBasicRt = rt.type({
+  /**
+   * The status of the sub case (open, closed, in-progress)
+   */
   status: CaseStatusRt,
 });
 
@@ -31,14 +34,41 @@ export const SubCaseAttributesRt = rt.intersection([
 ]);
 
 export const SubCasesFindRequestRt = rt.partial({
+  /**
+   * The status of the sub case (open, closed, in-progress)
+   */
   status: CaseStatusRt,
+  /**
+   * Operator to use for the `search` field
+   */
   defaultSearchOperator: rt.union([rt.literal('AND'), rt.literal('OR')]),
+  /**
+   * The fields in the entity to return in the response
+   */
   fields: rt.array(rt.string),
+  /**
+   * The page of objects to return
+   */
   page: NumberFromString,
+  /**
+   * The number of objects to include in each page
+   */
   perPage: NumberFromString,
+  /**
+   * An Elasticsearch simple_query_string
+   */
   search: rt.string,
+  /**
+   * The fields to perform the simple_query_string parsed query against
+   */
   searchFields: rt.array(rt.string),
+  /**
+   * The field to use for sorting the found objects.
+   */
   sortField: rt.string,
+  /**
+   * The order to sort by
+   */
   sortOrder: rt.union([rt.literal('desc'), rt.literal('asc')]),
   owner: rt.string,
 });

x-pack/plugins/cases/common/api/saved_object.ts

@@ -23,16 +23,49 @@ export const NumberFromString = new rt.Type<number, string, unknown>(
 const ReferenceRt = rt.type({ id: rt.string, type: rt.string });
 
 export const SavedObjectFindOptionsRt = rt.partial({
+  /**
+   * The default operator to use for the simple_query_string
+   */
   defaultSearchOperator: rt.union([rt.literal('AND'), rt.literal('OR')]),
+  /**
+   * The operator for controlling the logic of the `hasReference` field
+   */
   hasReferenceOperator: rt.union([rt.literal('AND'), rt.literal('OR')]),
+  /**
+   * Filter by objects that have an association to another object
+   */
   hasReference: rt.union([rt.array(ReferenceRt), ReferenceRt]),
+  /**
+   * The fields to return in the attributes key of the response
+   */
   fields: rt.array(rt.string),
+  /**
+   * The filter is a KQL string with the caveat that if you filter with an attribute from your saved object type, it should look like that: savedObjectType.attributes.title: "myTitle". However, If you use a root attribute of a saved object such as updated_at, you will have to define your filter like that: savedObjectType.updated_at > 2018-12-22
+   */
   filter: rt.string,
+  /**
+   * The page of objects to return
+   */
   page: NumberFromString,
+  /**
+   * The number of objects to return for a page
+   */
   perPage: NumberFromString,
+  /**
+   * An Elasticsearch simple_query_string query that filters the objects in the response
+   */
   search: rt.string,
+  /**
+   * The fields to perform the simple_query_string parsed query against
+   */
   searchFields: rt.array(rt.string),
+  /**
+   * Sorts the response. Includes "root" and "type" fields. "root" fields exist for all saved objects, such as "updated_at". "type" fields are specific to an object type, such as fields returned in the attributes key of the response. When a single type is defined in the type parameter, the "root" and "type" fields are allowed, and validity checks are made in that order. When multiple types are defined in the type parameter, only "root" fields are allowed
+   */
   sortField: rt.string,
+  /**
+   * Order to sort the response
+   */
   sortOrder: rt.union([rt.literal('desc'), rt.literal('asc')]),
 });
 

x-pack/plugins/cases/docs/README.md

@@ -0,0 +1,37 @@
+# Cases Client API Docs
+
+This directory contains generated docs using `typedoc` for the cases client API that can be called from other server
+plugins. This README will describe how to generate a new version of these markdown docs in the event that new methods
+or parameters are added.
+
+## TypeDoc Info
+
+See more info at: <https://typedoc.org/>
+and: <https://www.npmjs.com/package/typedoc-plugin-markdown> for the markdown plugin
+
+## Install dependencies
+
+```bash
+yarn global add typedoc typedoc-plugin-markdown
+```
+
+## Generate the docs
+
+```bash
+cd x-pack/plugins/cases/docs
+npx typedoc --options cases_client_typedoc.json
+```
+
+After running the above commands the files in the `server` directory will be updated to match the new tsdocs.
+If additional markdown directory should be created we can create a new typedoc configuration file and adjust the `out`
+directory accordingly.
+
+## Troubleshooting
+
+If you run into tsc errors that seem unrelated to the cases plugin try executing these commands before running `typedoc`
+
+```bash
+cd <kibana root dir>
+npx yarn kbn bootstrap
+node scripts/build_ts_refs.js --clean --no-cache
+```

x-pack/plugins/cases/docs/cases_client/cases_client_api.md

@@ -0,0 +1,22 @@
+Cases Client API Interface
+
+# Cases Client API Interface
+
+## Table of contents
+
+### Modules
+
+- [attachments/add](modules/attachments_add.md)
+- [attachments/client](modules/attachments_client.md)
+- [attachments/delete](modules/attachments_delete.md)
+- [attachments/get](modules/attachments_get.md)
+- [attachments/update](modules/attachments_update.md)
+- [cases/client](modules/cases_client.md)
+- [cases/get](modules/cases_get.md)
+- [cases/push](modules/cases_push.md)
+- [client](modules/client.md)
+- [configure/client](modules/configure_client.md)
+- [stats/client](modules/stats_client.md)
+- [sub\_cases/client](modules/sub_cases_client.md)
+- [typedoc\_interfaces](modules/typedoc_interfaces.md)
+- [user\_actions/client](modules/user_actions_client.md)