@resolution/jira-api-client 0.1.0

package/src/openapi/software/services/remote-links-service.ts

@@ -0,0 +1,653 @@
+// DO NOT EDIT!
+// This file is generated by "api-typescript-generator".
+// To update this file run "yarn build:openapi".
+import { z } from "zod";
+
+import * as commonHttpClient from "../core/common-http-client";
+import { CommonHttpService } from "../core/common-http-service";
+import { validationSchemaStorage } from "../validation-schema-storage";
+/**
+ * APIs related to integrating Remote Links data with Jira Software. These APIs
+ * are available to Atlassian Connect
+ * apps. To use these APIs you must have the Remote Link 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 Remote Link module allows third-party providers to add a generic link
+ * through a public REST API and associate it with Jira issues or services.
+ *
+ * Supplied remote link information will be presented in the right sidebar of the
+ * new Jira issue view under Releases.
+ *
+ * This module also provides actions, which allows users to perform an action on
+ * the remote link.
+ *
+ * Note that the module key and name are not private and should therefore 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": {
+ *     "jiraRemoteLinkInfoProvider": {
+ *       "homeUrl": "https://my-remotelink-provider.com",
+ *       "logoUrl": "https://my-remotelink-provider.com/images/logo.svg",
+ *       "documentationUrl":
+ * "https://my-remotelink-provider.com/docs/jira-integration",
+ *       "actions": [
+ *         {
+ *           "actionId": "action-1",
+ *           "actionLabel": {
+ *             "value": {
+ *               "value": "Acknowledge"
+ *             }
+ *           },
+ *           "templateUrl": "https://my-remotelink-provider.com/ack/{ack-id}"
+ *         }
+ *       ],
+ *       "name": {
+ *         "value": "My Remote Link Provider"
+ *       },
+ *       "key": "remotelink-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        | Optional actions that can be performed by
+ * Jira users on the remote link
+ *
+ * ### Actions object
+ *
+ * | Property    | type   | Description
+ *
+ * | Required |
+ * |-------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+ * | actionId    | string | A key to identify a specific action. Used for
+ * associating a specific Remote link to an action of this ID.  <br> The actionId
+ * of an action must be unique across all actions.
+ *                                     | Yes      |
+ * | actionLabel | object | The actionLabel of an Action is shown visibly to the
+ * User alongside the Remote Link.
+ *
+ * | Yes      |
+ * | templateUrl | string | The templateUrl of an Action is a template where
+ * strings can be substituted into the URL for a specific Remote Link. <br>
+ * Strings used in the templateUrl must be passed in via an attribute map when
+ * associating an action with a remote link. | Yes      |
+ *
+ * ### ActionLabel Object
+ *
+ * | Property | type          | Description
+ *
+ * | Required |
+ * |----------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+ * | value    | object (i18n) | The label shown on the UI. This object supports
+ * [internationalization](https://developer.atlassian.com/cloud/jira/software/internationalization/).
+ * | Yes      |
+ */
+export class RemoteLinksService extends CommonHttpService {
+  /**
+   * Delete the Remote Link data currently stored for the given ID.
+   *
+   * Deletion is performed asynchronously. The `getRemoteLinkById` operation can be
+   * used to confirm that data has been
+   * deleted successfully (if needed).
+   *
+   * Only Connect apps that define the `jiraRemoteLinkInfoProvider` module, and
+   * on-premise integrations, can access this resource.
+   * This resource requires the 'DELETE' scope for Connect apps.
+   *
+   * @path {DELETE} /rest/remotelinks/1.0/remotelink/{remoteLinkId}
+   */
+  deleteRemoteLinkById({
+    remoteLinkId,
+    updateSequenceNumber,
+    authorization,
+  }: {
+    /** The ID of the Remote Link to fetch. */
+    remoteLinkId: string;
+    /**
+     * This parameter usage is no longer supported.
+     *
+     * An optional `_updateSequenceNumber` to use to control deletion.
+     *
+     * Only stored data with an `updateSequenceNumber` less than or equal to that
+     * provided will be deleted.
+     * This can be used help ensure submit/delete requests are applied correctly if
+     * issued close together.
+     *
+     * @deprecated
+     */
+    updateSequenceNumber?: number;
+    /**
+     * All requests must be signed with either a Connect JWT token or OAuth token for
+     * an on-premise integration that
+     * corresponds to an app installed in Jira.
+     *
+     * If the Connect JWT token corresponds to an app that does not define
+     * `jiraRemoteLinkInfoProvider` module it will be rejected with a 403.
+     *
+     * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+     * details about Connect JWT tokens.
+     * See
+     * https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/
+     * for details about on-premise integrations.
+     */
+    authorization: string;
+  }): Promise<void> {
+    return this.getClientInstance()
+      .request({
+        path: "/rest/remotelinks/1.0/remotelink/{remoteLinkId}",
+        method: "DELETE",
+        pathParams: {
+          remoteLinkId,
+        },
+        query: {
+          _updateSequenceNumber: updateSequenceNumber,
+        },
+        headers: {
+          Authorization: authorization,
+        },
+      })
+      .then(commonHttpClient.discardResult);
+  }
+  /**
+   * Bulk delete all Remote Links data that match the given request.
+   *
+   * One or more query params must be supplied to specify Properties to delete by.
+   * Optional param `_updateSequenceNumber` is no longer supported. 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 `submitRemoteLinks` operation for more details.
+   *
+   * e.g. DELETE /bulkByProperties?accountId=account-123&repoId=repo-345
+   *
+   * Deletion is performed asynchronously. The `getRemoteLinkById` operation can be
+   * used to confirm that data has been
+   * deleted successfully (if needed).
+   *
+   * Only Connect apps that define the `jiraRemoteLinkInfoProvider` module, and
+   * on-premise integrations, can access this resource.
+   * This resource requires the 'DELETE' scope for Connect apps.
+   *
+   * @path {DELETE} /rest/remotelinks/1.0/bulkByProperties
+   */
+  deleteRemoteLinksByProperty({
+    updateSequenceNumber,
+    params,
+    authorization,
+  }: {
+    /**
+     * This parameter usage is no longer supported.
+     *
+     * An optional `_updateSequenceNumber` to use to control deletion.
+     *
+     * Only stored data with an `updateSequenceNumber` less than or equal to that
+     * provided will be deleted.
+     * This can be used help ensure submit/delete requests are applied correctly if
+     * issued close together.
+     *
+     * If not provided, all stored data that matches the request will be deleted.
+     *
+     * @deprecated
+     */
+    updateSequenceNumber?: number;
+    /**
+     * Free-form query parameters to specify which properties to delete by. Properties
+     * refer to the arbitrary
+     * information the provider tagged Remote Links with previously.
+     *
+     * For example, if the provider previously tagged a remote link with accountId:
+     *   "properties": {
+     *     "accountId": "account-123"
+     *   }
+     *
+     * And now they want to delete Remote Links in bulk by that specific accountId as
+     * follows:
+     * e.g. DELETE /bulkByProperties?accountId=account-123
+     */
+    params?: {
+      [key: string]: unknown;
+    };
+    /**
+     * All requests must be signed with either a Connect JWT token or OAuth token for
+     * an on-premise integration that
+     * corresponds to an app installed in Jira.
+     *
+     * If the Connect JWT token corresponds to an app that does not define
+     * `jiraRemoteLinkInfoProvider` module it will be rejected with a 403.
+     *
+     * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+     * details about Connect JWT tokens.
+     * See
+     * https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/
+     * for details about on-premise integrations.
+     */
+    authorization: string;
+  }): Promise<void> {
+    return this.getClientInstance()
+      .request({
+        path: "/rest/remotelinks/1.0/bulkByProperties",
+        method: "DELETE",
+        query: {
+          _updateSequenceNumber: updateSequenceNumber,
+          params,
+        },
+        headers: {
+          Authorization: authorization,
+        },
+      })
+      .then(commonHttpClient.discardResult);
+  }
+  /**
+   * Retrieve the currently stored Remote Link 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 `jiraRemoteLinkInfoProvider` module, and
+   * on-premise integrations, can access this resource.
+   * This resource requires the 'READ' scope for Connect apps.
+   *
+   * @returns The Remote Link data currently stored for the given ID.
+   * @path {GET} /rest/remotelinks/1.0/remotelink/{remoteLinkId}
+   */
+  getRemoteLinkById({
+    remoteLinkId,
+    authorization,
+  }: {
+    /** The ID of the Remote Link to fetch. */
+    remoteLinkId: string;
+    /**
+     * All requests must be signed with either a Connect JWT token or OAuth token for
+     * an on-premise integration that
+     * corresponds to an app installed in Jira.
+     *
+     * If the Connect JWT token corresponds to an app that does not define
+     * `jiraRemoteLinkInfoProvider` module it will be rejected with a 403.
+     *
+     * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+     * details about Connect JWT tokens.
+     * See
+     * https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/
+     * for details about on-premise integrations.
+     */
+    authorization: string;
+  }): Promise<unknown> {
+    return this.getClientInstance()
+      .request({
+        path: "/rest/remotelinks/1.0/remotelink/{remoteLinkId}",
+        method: "GET",
+        pathParams: {
+          remoteLinkId,
+        },
+        headers: {
+          Authorization: authorization,
+        },
+      })
+      .then(
+        this.getClientInstance().responseHandler({
+          200: {
+            "application/json": "json",
+          },
+        }),
+      )
+      .then(
+        commonHttpClient.castResponse<{
+          status: 200;
+          mediaType: "application/json";
+          body: unknown;
+        }>(),
+      )
+      .then(
+        validationSchemaStorage.validator(
+          "RemoteLinksService.getRemoteLinkById.response",
+        ),
+      )
+      .then(commonHttpClient.getBody);
+  }
+  /**
+   * Update / insert Remote Link data.
+   *
+   * Remote Links are identified by their ID, existing Remote Link data for the same
+   * ID will be replaced if it
+   * exists and the updateSequenceId 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 `getRemoteLinkById` operation can be used to confirm that data has been
+   * stored successfully (if needed).
+   *
+   * In the case of multiple Remote Links being submitted in one request, each is
+   * validated individually prior to
+   * submission. Details of which Remote LInk failed submission (if any) are
+   * available in the response object.
+   *
+   * Only Connect apps that define the `jiraRemoteLinkInfoProvider` module can
+   * access this resource. This resource
+   * requires the 'WRITE' scope for Connect apps.
+   *
+   * @returns Submission accepted. Each submitted Remote Link that is of a valid format will
+   * be eventually available in
+   * Jira.
+   *
+   * Details of which Remote Links were submitted and which failed submission (due
+   * to data format problems etc.)
+   * are available in the response object.
+   * @path {POST} /rest/remotelinks/1.0/bulk
+   */
+  submitRemoteLinks({
+    authorization,
+    requestBody,
+  }: {
+    /**
+     * All requests must be signed with a Connect JWT token that corresponds to an app
+     * installed in Jira.
+     *
+     * If the Connect JWT token corresponds to an app that does not define
+     * `jiraRemoteLinkInfoProvider` module it will be rejected with a 403.
+     *
+     * See https://developer.atlassian.com/blog/2015/01/understanding-jwt/ for more
+     * details about Connect JWT tokens.
+     * See
+     * https://developer.atlassian.com/cloud/jira/software/integrate-jsw-cloud-with-onpremises-tools/
+     * for details about on-premise integrations.
+     */
+    authorization: string;
+    /** Remote Links data to submit. */
+    requestBody: {
+      /**
+       * Properties
+       *
+       * Properties assigned to Remote Link data that can then be used for delete /
+       * query operations.
+       *
+       * Examples might be an account or user ID that can then be used to clean up data
+       * if an account is removed from
+       * the Provider system.
+       *
+       * Properties are supplied as key/value pairs, a maximum of 5 properties can be
+       * supplied, and keys must not
+       * contain ':' or start with '_'.
+       *
+       * @example {
+       *     "accountId": "account-234",
+       *     "projectId": "project-123"
+       * }
+       */
+      properties?: {
+        [key: string]: string;
+      };
+      /**
+       * A list of Remote Links to submit to Jira.
+       *
+       * Each Remote Link may be associated with one or more Jira issue keys, and will
+       * be associated with any properties
+       * included in this request.
+       */
+      remoteLinks: unknown[];
+      /**
+       * ProviderMetadata
+       *
+       * Information about the provider. This is useful for auditing, logging,
+       * debugging, and other internal uses. It is
+       * not considered private information. Hence, it may not contain personally
+       * identifiable information.
+       */
+      providerMetadata?: {
+        /**
+         * An optional name of the source of the Remote Links data.
+         *
+         * @example Opsgenie 6.10.2
+         */
+        product?: string;
+      } & {
+        [key: string]: unknown;
+      };
+    } & {
+      [key: string]: unknown;
+    };
+  }): Promise<
+    {
+      /**
+       * The IDs of Remote Links that have been accepted for submission.
+       *
+       * A Remote Link may be rejected if it was only associated with unknown issue
+       * keys, unknown service IDs, or if
+       * the submitted data for that Remote Link does not match the required schema.
+       *
+       * Note that a Remote Link that isn't updated due to it's `updateSequenceNumber`
+       * being out of order is not
+       * considered a failed submission.
+       *
+       * @example [
+       *     "111-222-333",
+       *     "444-555-666"
+       * ]
+       */
+      acceptedRemoteLinks?: string[];
+      /**
+       * Details of Remote Links that have not been accepted for submission, usually due
+       * to a problem with the request data.
+       *
+       * A Remote Link may be rejected if it was only associated with unknown issue
+       * keys, unknown service IDs, or
+       * if the submitted data for the Remote Link does not match the required schema.
+       *
+       * The object (if present) will be keyed by Remote Link ID and include any errors
+       * associated with that
+       * Remote Link that have prevented it being submitted.
+       */
+      rejectedRemoteLinks?: {
+        [key: string]: ({
+          /** A human-readable message describing the error. */
+          message: string;
+          /**
+           * An optional trace ID that can be used by Jira developers to locate the source
+           * of the error.
+           */
+          errorTraceId?: string;
+        } & {
+          [key: string]: unknown;
+        })[];
+      };
+      /**
+       * Issue keys or services IDs or keys that are not known on this Jira instance (if
+       * any).
+       */
+      unknownAssociations?: (
+        | ({
+            /**
+             * Defines the asssociation type.
+             *
+             * @example issueKeys
+             */
+            associationType: "issueKeys";
+            /**
+             * The Jira issue keys to associate the Remote Link information with.
+             *
+             * The number of values counted across all associationTypes (issueKeys,
+             * issueIdOrKeys and serviceIdOrKeys) must not exceed a limit of 500.
+             */
+            values: string[];
+          } & {
+            [key: string]: unknown;
+          })
+        | ({
+            /**
+             * Defines the asssociation type.
+             *
+             * @example serviceIdOrKeys
+             */
+            associationType: "serviceIdOrKeys";
+            /**
+             * The service id or keys to associate the Remote Link information with.
+             *
+             * The number of values counted across all associationTypes (issueKeys,
+             * issueIdOrKeys and serviceIdOrKeys) must not exceed a limit of 500.
+             */
+            values: string[];
+          } & {
+            [key: string]: unknown;
+          })
+      )[];
+    } & {
+      [key: string]: unknown;
+    }
+  > {
+    return this.getClientInstance()
+      .request({
+        path: "/rest/remotelinks/1.0/bulk",
+        method: "POST",
+        headers: {
+          Authorization: authorization,
+          "Content-Type": "application/json",
+        },
+        body: requestBody,
+      })
+      .then(
+        this.getClientInstance().responseHandler({
+          202: {
+            "application/json": "json",
+          },
+        }),
+      )
+      .then(
+        commonHttpClient.castResponse<{
+          status: 202;
+          mediaType: "application/json";
+          body: {
+            acceptedRemoteLinks?: string[];
+            rejectedRemoteLinks?: {
+              [key: string]: ({
+                message: string;
+                errorTraceId?: string;
+              } & {
+                [key: string]: unknown;
+              })[];
+            };
+            unknownAssociations?: (
+              | ({
+                  associationType: "issueKeys";
+                  values: string[];
+                } & {
+                  [key: string]: unknown;
+                })
+              | ({
+                  associationType: "serviceIdOrKeys";
+                  values: string[];
+                } & {
+                  [key: string]: unknown;
+                })
+            )[];
+          } & {
+            [key: string]: unknown;
+          };
+        }>(),
+      )
+      .then(
+        validationSchemaStorage.validator(
+          "RemoteLinksService.submitRemoteLinks.response",
+        ),
+      )
+      .then(commonHttpClient.getBody);
+  }
+  static initialize() {
+    validationSchemaStorage.registerExtensible(
+      "RemoteLinksService.submitRemoteLinks.response",
+      z
+        .object({
+          status: z.literal(202),
+          mediaType: z.literal("application/json"),
+          body: z
+            .object({
+              acceptedRemoteLinks: z.array(z.string()).optional(),
+              rejectedRemoteLinks: z
+                .object({})
+                .catchall(
+                  z.array(
+                    z
+                      .object({
+                        message: z.string(),
+                        errorTraceId: z.string().optional(),
+                      })
+                      .catchall(z.unknown()),
+                  ),
+                )
+                .optional(),
+              unknownAssociations: z
+                .array(
+                  z.union([
+                    z
+                      .object({
+                        associationType: z.enum(["issueKeys"]),
+                        values: z
+                          .array(
+                            z
+                              .string()
+                              .regex(new RegExp("^\\w{1,255}-\\d{1,255}$")),
+                          )
+                          .min(1)
+                          .max(500),
+                      })
+                      .catchall(z.unknown()),
+                    z
+                      .object({
+                        associationType: z.enum(["serviceIdOrKeys"]),
+                        values: z.array(z.string().max(255)).min(1).max(500),
+                      })
+                      .catchall(z.unknown()),
+                  ]),
+                )
+                .optional(),
+            })
+            .catchall(z.unknown()),
+        })
+        .describe("RemoteLinksService.submitRemoteLinks.response"),
+    );
+    validationSchemaStorage.registerExtensible(
+      "RemoteLinksService.getRemoteLinkById.response",
+      z
+        .object({
+          status: z.literal(200),
+          mediaType: z.literal("application/json"),
+          body: z.unknown(),
+        })
+        .describe("RemoteLinksService.getRemoteLinkById.response"),
+    );
+  }
+}