@resolution/jira-api-client 0.1.6 → 0.3.0

package/lib/openapi/software/services/OperationsService.d.ts

@@ -0,0 +1,598 @@
+import { CommonHttpService } from "../core/CommonHttpService";
+import { type OperationsWorkspaceIds, type SubmitIncidentsRequest, type SubmitIncidentsResponse, type SubmitOperationsWorkspacesRequest, type SubmitOperationsWorkspacesResponse } from "../models/operations";
+/**
+ * APIs related to integrating Incident and Post-Incident Review (PIR) data with
+ * Jira Software. These APIs are available to Atlassian Connect
+ * apps. To use these APIs you must have the Operations module in your app's
+ * descriptor. Read more about Jira Software modules
+ * [here](https://developer.atlassian.com/cloud/jira/software/about-jira-modules/).
+ *
+ * # Module
+ *
+ * The Operations module allows third-party providers to add incident and PIR
+ * information through a public REST API.
+ *
+ * Supplied incident information will be presented in the Incidents page in Jira
+ * Software, and as a link to any issues created via the Incidents Page.
+ *
+ * This module also provides actions, one which allows Jira to provide a direct
+ * link to the operations provider where the user can create a post-incident
+ * review and two which allow Jira to search for relevant workspaces and devops
+ * components.
+ *
+ * Note that the module key and name are not private and therefore should not
+ * contain any sensitive or personally identifiable information.
+ *
+ * ## Example Module
+ *
+ * An example can also be found at
+ * [jira-data-provider-sample-addon](https://bitbucket.org/atlassianlabs/jira-data-provider-sample-addon/src/master/),
+ * which has an `atlassian-connect.json`.
+ *
+ * ```
+ * {
+ *   "modules": {
+ *     "jiraOperationsInfoProvider": {
+ *       "homeUrl": "https://my-operations-provider.com",
+ *       "logoUrl": "https://my-operations-provider.com/images/logo.svg",
+ *       "documentationUrl":
+ * "https://my-operations-provider.com/docs/jira-integration",
+ *       "actions": {
+ *           "fetchWorkspaces": {
+ *               "templateUrl": "/workspaces/list"
+ *           },
+ *           "searchContainers": {
+ *               "templateUrl": "/containers/search"
+ *           },
+ *           "createPostIncidentReview": {
+ *               "url":
+ * "https://my-operations-provider.com/my-workspace/create-post-incident-review?affected-component={component-id}&incident={incident-id}
+ *           }
+ *       },
+ *       "name": {
+ *         "value": "My Operations Provider"
+ *       },
+ *       "key": "operations-integration"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Properties
+ *
+ * | Property         | type          | Description
+ *
+ * | Required |
+ * |------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+ * | key              | string        | A key to identify this module.  Must match
+ * `^[a-zA-Z0-9-]+$` pattern, with a max length of 100
+ *                      | Yes      |
+ * | name             | object (i18N) | A human readable name. This object
+ * supports
+ * [internationalization](https://developer.atlassian.com/cloud/jira/software/internationalization/).
+ * | Yes      |
+ * | homeUrl          | string        | URL to the provider’s homepage
+ *
+ * | Yes      |
+ * | logoUrl          | string        | Optional URL to the provider’s logo, which
+ * will be displayed in the UI
+ *                      |          |
+ * | documentationUrl | string        | Optional URL to documentation about the
+ * provider’s Jira integration
+ *                         |          |
+ * | actions          | object        | Actions the can be used by Jira to improve
+ * the integrated experience
+ *                      | Yes      |
+ *
+ * ### Actions object
+ *
+ * | Property               | type   | Description
+ *
+ * | Required |
+ * |------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+ * | fetchWorkspaces | object | An action defined by the provider to allow Jira to
+ * retrieve details about operations workspaces via a post endpoint.
+ *
+ * | Yes      |
+ * | searchContainers | object | An action defined by the provider to allow Jira
+ * to search using details about devops components via a get endpoint.
+ *
+ * | Yes      |
+ * | createPostIncidentReview | object | An action defined by the provider to
+ * allow Jira to create a new Post-Incident Review object via a post endpoint.
+ *
+ * |       |
+ */
+export declare class OperationsService extends CommonHttpService {
+    /**
+     * Bulk delete all Entties that match the given request.
+     *
+     * One or more query params must be supplied to specify Properties to delete by.
+     * If more than one Property is provided, data will be deleted that matches ALL of
+     * the Properties (e.g. treated as an AND).
+     * See the documentation for the submitEntity operation for more details.
+     *
+     * e.g. DELETE /bulkByProperties?accountId=account-123&createdBy=user-456
+     *
+     * Deletion is performed asynchronously. The getIncidentById operation can be used
+     * to confirm that data has been deleted successfully (if needed).
+     *
+     * Only Connect apps that define the `jiraOperationsInfoProvider` module can
+     * access this resource.
+     * This resource requires the 'DELETE' scope for Connect apps.
+     *
+     * @path {DELETE} /rest/operations/1.0/bulkByProperties
+     */
+    deleteEntityByProperty({ authorization, }: {
+        /**
+         * All requests must be signed with a Connect JWT token that corresponds to the
+         * Provider app installed in Jira.
+         *
+         * If the JWT token corresponds to an app that does not define Operations
+         * Information module it will be rejected with a 403.
+         *
+         * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+         * details.
+         */
+        authorization: string;
+    }): Promise<void>;
+    /**
+     * Delete the Incident data currently stored for the given ID.
+     *
+     * Deletion is performed asynchronously. The getIncidentById operation can be used
+     * to confirm that data has been deleted successfully (if needed).
+     *
+     * Only Connect apps that define the `jiraOperationsInfoProvider` module can
+     * access this resource.
+     * This resource requires the 'DELETE' scope for Connect apps.
+     *
+     * @path {DELETE} /rest/operations/1.0/incidents/{incidentId}
+     */
+    deleteIncidentById({ incidentId, authorization, }: {
+        /** The ID of the Incident to delete. */
+        incidentId: string;
+        /**
+         * All requests must be signed with a Connect JWT token that corresponds to the
+         * Provider app installed in Jira.
+         *
+         * If the JWT token corresponds to an app that does not define Operations
+         * Information module it will be rejected with a 403.
+         *
+         * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+         * details.
+         */
+        authorization: string;
+    }): Promise<void>;
+    /**
+     * Delete the Review data currently stored for the given ID.
+     *
+     * Deletion is performed asynchronously. The getReviewById operation can be used
+     * to confirm that data has been deleted successfully (if needed).
+     *
+     * Only Connect apps that define the `jiraOperationsInfoProvider` module can
+     * access this resource.
+     * This resource requires the 'DELETE' scope for Connect apps.
+     *
+     * @path {DELETE} /rest/operations/1.0/post-incident-reviews/{reviewId}
+     */
+    deleteReviewById({ reviewId, authorization, }: {
+        /** The ID of the Review to delete. */
+        reviewId: string;
+        /**
+         * All requests must be signed with a Connect JWT token that corresponds to the
+         * Provider app installed in Jira.
+         *
+         * If the JWT token corresponds to an app that does not define Operations
+         * Information module it will be rejected with a 403.
+         *
+         * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+         * details.
+         */
+        authorization: string;
+    }): Promise<void>;
+    /**
+     * Bulk delete all Operations Workspaces that match the given request.
+     *
+     * Only Connect apps that define the `jiraOperationsInfoProvider` module can
+     * access this resource.
+     * This resource requires the 'DELETE' scope for Connect apps.
+     *
+     * e.g. DELETE /bulk?workspaceIds=111-222-333,444-555-666
+     *
+     * @path {DELETE} /rest/operations/1.0/linkedWorkspaces/bulk
+     */
+    deleteWorkspaces({ authorization, }: {
+        /**
+         * All requests must be signed with a Connect JWT token that corresponds to the
+         * Provider app installed in Jira.
+         *
+         * If the JWT token corresponds to an app that does not define the Operations
+         * module it will be rejected with a 403.
+         *
+         * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+         * details.
+         */
+        authorization: string;
+    }): Promise<void>;
+    /**
+     * Retrieve the currently stored Incident data for the given ID.
+     *
+     * The result will be what is currently stored, ignoring any pending updates or
+     * deletes.
+     *
+     * Only Connect apps that define the `jiraOperationsInfoProvider` module can
+     * access this resource.
+     * This resource requires the 'READ' scope for Connect apps.
+     *
+     * @returns The Incident data currently stored for the given ID.
+     * @path {GET} /rest/operations/1.0/incidents/{incidentId}
+     */
+    getIncidentById({ incidentId, authorization, }: {
+        /** The ID of the Incident to fetch. */
+        incidentId: string;
+        /**
+         * All requests must be signed with a Connect JWT token that corresponds to the
+         * Provider app installed in Jira.
+         *
+         * If the JWT token corresponds to an app that does not define Operations
+         * Information module it will be rejected with a 403.
+         *
+         * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+         * details.
+         */
+        authorization: string;
+    }): Promise<{
+        /**
+         * The IncidentData schema version used for this incident data.
+         *
+         * Placeholder to support potential schema changes in the future.
+         *
+         * @example 1
+         */
+        schemaVersion: "1.0";
+        /**
+         * The identifier for the Incident. Must be unique for a given Provider.
+         *
+         * @example 111-222-333
+         */
+        id: string;
+        /**
+         * An ID used to apply an ordering to updates for this Incident in the case of
+         * out-of-order receipt of update requests.
+         *
+         * This can be any monotonically increasing number. A suggested implementation is
+         * to use epoch millis from the Provider system, but other alternatives are valid
+         * (e.g. a Provider could store a counter against each Incident and increment that
+         * on each update to Jira).
+         *
+         * Updates for a Incident that are received with an updateSqeuenceId lower than
+         * what is currently stored will be ignored.
+         *
+         * @example 1523494301448
+         */
+        updateSequenceNumber: number;
+        /**
+         * The IDs of the Components impacted by this Incident. Must be unique for a given
+         * Provider.
+         *
+         * @example [
+         *     "111-222-333",
+         *     "444-555-666"
+         * ]
+         */
+        affectedComponents: string[];
+        /**
+         * The human-readable summary for the Incident. Will be shown in the UI.
+         *
+         * If not provided, will use the ID for display.
+         *
+         * @example Unable to log into VPN
+         */
+        summary: string;
+        /**
+         * A description of the issue in Markdown format. Will be shown in the UI and used
+         * when creating Jira Issues.
+         *
+         * @example null
+         */
+        description: string;
+        /**
+         * A URL users can use to link to a summary view of this incident, if appropriate.
+         *
+         * This could be any location that makes sense in the Provider system (e.g. if the
+         * summary information comes from a specific project, it might make sense to link
+         * the user to the incident in that project).
+         *
+         * @example https://example.com/project/ITHELPDESK-9/summary
+         */
+        url: string;
+        /**
+         * The timestamp to present to the user that shows when the Incident was raised.
+         *
+         * Expected format is an RFC3339 formatted string.
+         *
+         * @example 2018-01-20T23:27:25.000Z
+         */
+        createdDate: string;
+        /**
+         * The last-updated timestamp to present to the user the last time the Incident
+         * was updated.
+         *
+         * Expected format is an RFC3339 formatted string.
+         *
+         * @example 2018-01-20T23:27:25.000Z
+         */
+        lastUpdated: string;
+        /**
+         * IncidentSeverity
+         *
+         * Severity information for a single Incident.
+         *
+         * This is the severity information that will be presented to the user on e.g. the
+         * Jira Incidents screen.
+         */
+        severity?: unknown;
+        /**
+         * IncidentStatus
+         *
+         * The current status of the Incident.
+         *
+         * @example open
+         */
+        status: "open" | "resolved" | "unknown";
+        /**
+         * The IDs of the Jira issues related to this Incident. Must be unique for a given
+         * Provider.
+         */
+        associations?: ({
+            /**
+             * the type of the association being made
+             *
+             * @example issueIdOrKeys
+             */
+            associationType?: "issueIdOrKeys" | "serviceIdOrKeys" | "ati:cloud:compass:event-source";
+            values?: string[];
+        } & {
+            [key: string]: unknown;
+        })[];
+    }>;
+    /**
+     * Retrieve the currently stored Review data for the given ID.
+     *
+     * The result will be what is currently stored, ignoring any pending updates or
+     * deletes.
+     *
+     * Only Connect apps that define the `jiraOperationsInfoProvider` module can
+     * access this resource.
+     * This resource requires the 'READ' scope for Connect apps.
+     *
+     * @returns The Review data currently stored for the given ID.
+     * @path {GET} /rest/operations/1.0/post-incident-reviews/{reviewId}
+     */
+    getReviewById({ reviewId, authorization, }: {
+        /** The ID of the Review to fetch. */
+        reviewId: string;
+        /**
+         * All requests must be signed with a Connect JWT token that corresponds to the
+         * Provider app installed in Jira.
+         *
+         * If the JWT token corresponds to an app that does not define Operations
+         * Information module it will be rejected with a 403.
+         *
+         * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+         * details.
+         */
+        authorization: string;
+    }): Promise<{
+        /**
+         * The PostIncidentReviewData schema version used for this post-incident review
+         * data.
+         *
+         * Placeholder to support potential schema changes in the future.
+         *
+         * @example 1
+         */
+        schemaVersion: "1.0";
+        /**
+         * The identifier for the Review. Must be unique for a given Provider.
+         *
+         * @example 111-222-333
+         */
+        id: string;
+        /**
+         * An ID used to apply an ordering to updates for this Review in the case of
+         * out-of-order receipt of update requests.
+         *
+         * This can be any monotonically increasing number. A suggested implementation is
+         * to use epoch millis from the Provider system, but other alternatives are valid
+         * (e.g. a Provider could store a counter against each Review and increment that
+         * on each update to Jira).
+         *
+         * Updates for a Review that are received with an updateSqeuenceId lower than what
+         * is currently stored will be ignored.
+         *
+         * @example 1523494301448
+         */
+        updateSequenceNumber: number;
+        /**
+         * The IDs of the Incidents covered by this Review. Must be unique for a given
+         * Provider.
+         *
+         * @example [
+         *     "111-222-333",
+         *     "444-555-666"
+         * ]
+         */
+        reviews: string[];
+        /**
+         * The human-readable summary for the Post-Incident Review. Will be shown in the
+         * UI.
+         *
+         * If not provided, will use the ID for display.
+         *
+         * @example PIR - Unable to log into VPN
+         */
+        summary: string;
+        /**
+         * A description of the review in Markdown format. Will be shown in the UI and
+         * used when creating Jira Issues.
+         *
+         * @example null
+         */
+        description: string;
+        /**
+         * A URL users can use to link to a summary view of this review, if appropriate.
+         *
+         * This could be any location that makes sense in the Provider system (e.g. if the
+         * summary information comes from a specific project, it might make sense to link
+         * the user to the review in that project).
+         *
+         * @example https://example.com/project/ITHELPDESK-9/summary
+         */
+        url: string;
+        /**
+         * The timestamp to present to the user that shows when the Review was raised.
+         *
+         * Expected format is an RFC3339 formatted string.
+         *
+         * @example 2018-01-20T23:27:25.000Z
+         */
+        createdDate: string;
+        /**
+         * The last-updated timestamp to present to the user the last time the Review was
+         * updated.
+         *
+         * Expected format is an RFC3339 formatted string.
+         *
+         * @example 2018-01-20T23:27:25.000Z
+         */
+        lastUpdated: string;
+        /**
+         * Review status
+         *
+         * The current status of the Post-Incident Review.
+         *
+         * @example open
+         */
+        status: "in progress" | "outstanding actions" | "completed" | "unknown";
+        /**
+         * The IDs of the Jira issues related to this Incident. Must be unique for a given
+         * Provider.
+         */
+        associations?: ({
+            /**
+             * the type of the association being made
+             *
+             * @example issueIdOrKeys
+             */
+            associationType?: "issueIdOrKeys" | "serviceIdOrKeys" | "ati:cloud:compass:event-source";
+            values?: string[];
+        } & {
+            [key: string]: unknown;
+        })[];
+    }>;
+    /**
+     * Retrieve the either all Operations Workspace IDs associated with the Jira site
+     * or a specific Operations Workspace ID for the given ID.
+     *
+     * The result will be what is currently stored, ignoring any pending updates or
+     * deletes.
+     *
+     * e.g. GET /workspace?workspaceId=111-222-333
+     *
+     * Only Connect apps that define the `jiraOperationsInfoProvider` module can
+     * access this resource.
+     * This resource requires the 'READ' scope for Connect apps.
+     *
+     * @returns Either the ID provided if stored or a list of available IDs.
+     * @path {GET} /rest/operations/1.0/linkedWorkspaces
+     */
+    getWorkspaces({ authorization, }: {
+        /**
+         * All requests must be signed with a Connect JWT token that corresponds to the
+         * Provider app installed in Jira.
+         *
+         * If the JWT token corresponds to an app that does not define the Operations
+         * Information module it will be rejected with a 403.
+         *
+         * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+         * details.
+         */
+        authorization: string;
+    }): Promise<OperationsWorkspaceIds>;
+    /**
+     * Update / insert Incident or Review data.
+     *
+     * Incidents and reviews are identified by their ID, and existing Incident and
+     * Review data for the same ID will be replaced if it exists and the
+     * updateSequenceNumber of existing data is less than the incoming data.
+     *
+     * Submissions are performed asynchronously. Submitted data will eventually be
+     * available in Jira; most updates are available within a short period of time,
+     * but may take some time during peak load and/or maintenance times. The
+     * getIncidentById or getReviewById operation can be used to confirm that data has
+     * been stored successfully (if needed).
+     *
+     * In the case of multiple Incidents and Reviews being submitted in one request,
+     * each is validated individually prior to submission. Details of which entities
+     * failed submission (if any) are available in the response object.
+     *
+     * A maximum of 1000 incidents can be submitted in one request.
+     *
+     * Only Connect apps that define the `jiraOperationsInfoProvider` module can
+     * access this resource.
+     * This resource requires the 'WRITE' scope for Connect apps.
+     *
+     * @returns Submission accepted. Each submitted Incident that is of a valid format will be
+     * eventually available in Jira.
+     *
+     * Details of which Incidents were submitted and which failed submission (due to
+     * data format problems etc.) are available in the response object.
+     * @path {POST} /rest/operations/1.0/bulk
+     */
+    submitEntity({ authorization, submitIncidentsRequest, }: {
+        /**
+         * All requests must be signed with a Connect JWT token that corresponds to the
+         * Provider app installed in Jira.
+         *
+         * If the JWT token corresponds to an app that does not define the Operations
+         * Information module it will be rejected with a 403.
+         *
+         * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+         * details.
+         */
+        authorization: string;
+        /** Incident data to submit. */
+        submitIncidentsRequest: SubmitIncidentsRequest;
+    }): Promise<SubmitIncidentsResponse>;
+    /**
+     * Insert Operations Workspace IDs to establish a relationship between them and
+     * the Jira site the app is installed in. If a relationship between the Workspace
+     * ID and Jira already exists then the workspace ID will be ignored and Jira will
+     * process the rest of the entries.
+     *
+     * Only Connect apps that define the `jiraOperationsInfoProvider` module can
+     * access this resource.
+     * This resource requires the 'WRITE' scope for Connect apps.
+     *
+     * @returns Submission accepted. Each submitted Operations Workspace ID will be linked to
+     * Jira.
+     * @path {POST} /rest/operations/1.0/linkedWorkspaces/bulk
+     */
+    submitOperationsWorkspaces({ authorization, submitOperationsWorkspacesRequest, }: {
+        /**
+         * All requests must be signed with a Connect JWT token that corresponds to the
+         * Provider app installed in Jira.
+         *
+         * If the JWT token corresponds to an app that does not define the Operations
+         * module it will be rejected with a 403.
+         *
+         * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+         * details.
+         */
+        authorization: string;
+        /** Operations Workspace ids to submit. */
+        submitOperationsWorkspacesRequest: SubmitOperationsWorkspacesRequest;
+    }): Promise<SubmitOperationsWorkspacesResponse>;
+    static initialize(): void;
+}