@resolution/jira-api-client 0.1.0

package/.eslintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  "parserOptions": { "project": `${__dirname}/tsconfig.json` }
+};

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# 0.1.0 (2024-05-28)
+
+
+### Features
+
+* initial version ([5c1e2d2](https://bitbucket.org/resolutiongmbh/atlassian-api-clients/commits/5c1e2d295fb3efe134ae9629fd6b5f00dc83d151))

package/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2024 resolution Reichert Network Solutions GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,12 @@
+# jira-api-client
+
+Atlassian Jira API client based on OpenAPI schema.
+
+Compatible with the following request/fetch Atlassian libraries:
+
+ * [atlassian-connect-express](https://bitbucket.org/atlassian/atlassian-connect-express)
+ * [atlassian-connect-js](https://bitbucket.org/atlassian/atlassian-connect-js)
+ * [@forge/api](https://developer.atlassian.com/cloud/jira/platform/forge/)
+ * [@forge/bridge](https://developer.atlassian.com/cloud/jira/platform/forge/)
+
+More details will follow.

package/config/api-typescript-generator.config.ts

@@ -0,0 +1,91 @@
+import {
+  addXAtlassianTokenNoCheckHeader,
+  setBinaryRequestBody,
+} from "@resolution/atlassian-api-common/config/binary";
+import {
+  addMultipartFileSchema,
+  setMultipartFileRequestBody,
+} from "@resolution/atlassian-api-common/config/binary";
+import { commonConfig } from "@resolution/atlassian-api-common/config/commonConfig";
+import { combinePatches } from "@resolution/atlassian-api-common/config/patch";
+import {
+  patchOperation,
+  patchPath,
+} from "@resolution/atlassian-api-common/config/patchOperation";
+import {
+  nullableProperties,
+  patchSchema,
+} from "@resolution/atlassian-api-common/config/patchSchema";
+import type { ApiTypescriptGeneratorConfig } from "api-typescript-generator";
+import * as path from "path";
+
+export const JIRA_PLATFORM_API_URL =
+  "https://dac-static.atlassian.com/cloud/jira/platform/swagger-v3.v3.json?_v=1.7207.0-0.1306.0";
+export const JIRA_SOFTWARE_API_URL =
+  "https://dac-static.atlassian.com/cloud/jira/software/swagger.v3.json?_v=1.7207.0-0.1306.0";
+
+const jiraPlatformApiSchemaPatches = combinePatches([
+  patchSchema("ChangeDetails", nullableProperties(["from", "fromString"])),
+  addMultipartFileSchema,
+]);
+
+const jiraPlatformApiOperationPatches = combinePatches([
+  patchPath(
+    "/rest/api/3/issue/{issueIdOrKey}/attachments",
+    patchOperation(
+      "post",
+      combinePatches([
+        addXAtlassianTokenNoCheckHeader,
+        setMultipartFileRequestBody,
+      ]),
+    ),
+  ),
+  patchPath(
+    "/rest/api/3/universal_avatar/type/{type}/owner/{entityId}",
+    patchOperation(
+      "post",
+      combinePatches([addXAtlassianTokenNoCheckHeader, setBinaryRequestBody]),
+    ),
+  ),
+]);
+
+const config: ApiTypescriptGeneratorConfig = {
+  generates: [
+    {
+      type: "openapiClient",
+      ...commonConfig,
+      document: {
+        source: {
+          type: "url",
+          url: JIRA_PLATFORM_API_URL,
+        },
+        patch: {
+          patchPaths: jiraPlatformApiOperationPatches,
+          patchSchemas: jiraPlatformApiSchemaPatches,
+        },
+      },
+      outputDirPath: path.join(__dirname, "..", "src/openapi/platform"),
+      client: {
+        name: "BaseJiraPlatformApiClient",
+        exportModels: true,
+      },
+    },
+    {
+      type: "openapiClient",
+      ...commonConfig,
+      document: {
+        source: {
+          type: "url",
+          url: JIRA_SOFTWARE_API_URL,
+        },
+      },
+      outputDirPath: path.join(__dirname, "..", "src/openapi/software"),
+      client: {
+        name: "BaseJiraSoftwareApiClient",
+        exportModels: true,
+      },
+    },
+  ],
+};
+
+export default config;

package/config/compare-schemas.ts

@@ -0,0 +1,307 @@
+import type {
+  OpenApiDocument,
+  OpenApiSchema,
+} from "api-typescript-generator/openapi";
+
+import {
+  JIRA_PLATFORM_API_URL,
+  JIRA_SOFTWARE_API_URL,
+} from "./api-typescript-generator.config";
+
+// ----------------------------------------------------------------------------
+// Different models are generated for JIRA platform and software APIs.
+// Some of the models have the same name.
+// It would be very inconvenient to export the models with the same name.
+// The plan is to export the models from Platform and those models from
+// Software that are not present in Platform.
+// This script compares the schemas of the JIRA platform and software APIs
+// to check if the schemas with the same names have the same structure.
+// If the schemas are different, the script exits with status 1.
+// Hopefully, this never happens.
+// ----------------------------------------------------------------------------
+
+async function loadOpenApiDocument(url: string): Promise<OpenApiDocument> {
+  return (await (await fetch(url)).json()) as OpenApiDocument;
+}
+
+type OpenApiSchemaOrRef = OpenApiSchema | { $ref: string };
+
+/**
+ * Compare two schemas and return the differences that could influence the compatibility.
+ */
+function compareSchemaTypes(
+  schema1: OpenApiSchemaOrRef,
+  schema2: OpenApiSchemaOrRef,
+  document1: OpenApiDocument,
+  document2: OpenApiDocument,
+): string[] {
+  const processed = new Set<OpenApiSchema>();
+  function queryDocument(path: string, document: OpenApiDocument): unknown {
+    let current = document as unknown;
+    for (const pathBit of path.substring(2).split("/")) {
+      current = (current as Record<string, unknown>)[pathBit];
+      if (current === undefined) {
+        throw new Error(`Could not find schema object by path "${path}".`);
+      }
+    }
+    return current;
+  }
+
+  function compare(
+    schema1: OpenApiSchemaOrRef,
+    schema2: OpenApiSchemaOrRef,
+    path: string[],
+  ) {
+    if (typeof schema1 === "object" && "$ref" in schema1) {
+      schema1 = queryDocument(schema1.$ref, document1) as OpenApiSchema;
+    }
+    if (typeof schema2 === "object" && "$ref" in schema2) {
+      schema2 = queryDocument(schema2.$ref, document2) as OpenApiSchema;
+    }
+    if (processed.has(schema1) || processed.has(schema2)) {
+      return [];
+    }
+    processed.add(schema1);
+    processed.add(schema2);
+
+    if (typeof schema1 === "boolean") {
+      if (schema1 !== schema2) {
+        return [
+          `Type mismatch at ${path.join(".")}: expected boolean, got ${schema2}`,
+        ];
+      }
+      return [];
+    }
+    if (typeof schema2 === "boolean") {
+      return [
+        `Type mismatch at ${path.join(".")}: expected boolean, got ${schema1}`,
+      ];
+    }
+    if (schema1.type !== schema2.type) {
+      return [
+        `Type mismatch at ${path.join(".")}: expected ${schema1.type}, got ${schema2.type}`,
+      ];
+    }
+    const differences: string[] = [];
+
+    if (
+      schema1.const !== undefined ||
+      (schema2.const !== undefined && schema1.const !== schema2.const)
+    ) {
+      differences.push(
+        `Const mismatch at ${path.join(".")}: expected ${schema1.const}, got ${schema2.const}`,
+      );
+    }
+
+    if (
+      (schema1.enum !== undefined || schema2.enum !== undefined) &&
+      (schema1.enum ?? [])
+        .map(String)
+        .sort((a, b) => a.localeCompare(b))
+        .join(",") !==
+        (schema2.enum ?? [])
+          .map(String)
+          .sort((a, b) => a.localeCompare(b))
+          .join(",")
+    ) {
+      differences.push(
+        `Enum mismatch at ${path.join(".")}: expected ${schema1.enum}, got ${schema2.enum}`,
+      );
+    }
+
+    if (schema1.nullable !== schema2.nullable) {
+      differences.push(
+        `Nullable mismatch at ${path.join(".")}: expected ${schema1.nullable}, got ${schema2.nullable}`,
+      );
+    }
+
+    if (schema1.type === "object") {
+      const properties1 = schema1.properties ?? {};
+      const properties2 = schema2.properties ?? {};
+      const propertyNames = new Set([
+        ...Object.keys(properties1),
+        ...Object.keys(properties2),
+      ]);
+      for (const propertyName of Array.from(propertyNames.values())) {
+        const propertyPath = path.concat(propertyName);
+        const property1 = properties1[propertyName];
+        if (property1 === undefined) {
+          differences.push(
+            `Property ${propertyPath.join(".")} is missing in the first schema`,
+          );
+          continue;
+        }
+        const property2 = properties2[propertyName];
+        if (property2 === undefined) {
+          differences.push(
+            `Property ${propertyPath.join(".")} is missing in the second schema`,
+          );
+          continue;
+        }
+        differences.push(...compare(property1, property2, propertyPath));
+      }
+      if (schema1.additionalProperties !== undefined) {
+        if (schema2.additionalProperties === undefined) {
+          differences.push(
+            `Additional properties are not allowed in the second schema at ${path.join(".")}`,
+          );
+        } else {
+          differences.push(
+            ...compare(
+              schema1.additionalProperties,
+              schema2.additionalProperties,
+              [...path, "[additionalProperties]"],
+            ),
+          );
+        }
+      } else if (schema2.additionalProperties !== undefined) {
+        differences.push(
+          `Additional properties are allowed in the second schema at ${path.join(".")}`,
+        );
+      }
+    }
+    if (schema1.type === "array") {
+      if (schema1.items !== undefined) {
+        if (schema2.items === undefined) {
+          differences.push(
+            `Items are missing in the second schema at ${path.join(".")}`,
+          );
+        } else {
+          differences.push(
+            ...compare(schema1.items, schema2.items, [...path, "[items]"]),
+          );
+        }
+      } else if (schema2.items !== undefined) {
+        differences.push(
+          `Items are missing in the first schema at ${path.join(".")}`,
+        );
+      }
+      if (schema1.prefixItems !== undefined) {
+        if (schema2.prefixItems === undefined) {
+          differences.push(
+            `Prefix items are missing in the second schema at ${path.join(".")}`,
+          );
+        } else {
+          if (schema1.prefixItems.length !== schema2.prefixItems.length) {
+            differences.push(
+              `Prefix items count mismatch at ${path.join(".")}`,
+            );
+          } else {
+            for (let i = 0; i < schema1.prefixItems.length; i++) {
+              differences.push(
+                ...compare(schema1.prefixItems[i], schema2.prefixItems[i], [
+                  ...path,
+                  `[prefixItems][${i}]`,
+                ]),
+              );
+            }
+          }
+        }
+      }
+    }
+    if (schema1.allOf !== undefined) {
+      if (schema2.allOf === undefined) {
+        differences.push(
+          `AllOf is missing in the second schema at ${path.join(".")}`,
+        );
+      } else {
+        if (schema1.allOf.length !== schema2.allOf.length) {
+          differences.push(`AllOf count mismatch at ${path.join(".")}`);
+        } else {
+          for (let i = 0; i < schema1.allOf.length; i++) {
+            differences.push(
+              ...compare(schema1.allOf[i], schema2.allOf[i], [
+                ...path,
+                `[allOf][${i}]`,
+              ]),
+            );
+          }
+        }
+      }
+    }
+    if (schema1.oneOf !== undefined) {
+      if (schema2.oneOf === undefined) {
+        differences.push(
+          `OneOf is missing in the second schema at ${path.join(".")}`,
+        );
+      } else {
+        if (schema1.oneOf.length !== schema2.oneOf.length) {
+          differences.push(`OneOf count mismatch at ${path.join(".")}`);
+        } else {
+          for (let i = 0; i < schema1.oneOf.length; i++) {
+            differences.push(
+              ...compare(schema1.oneOf[i], schema2.oneOf[i], [
+                ...path,
+                `[oneOf][${i}]`,
+              ]),
+            );
+          }
+        }
+      }
+    }
+    if (schema1.anyOf !== undefined) {
+      if (schema2.anyOf === undefined) {
+        differences.push(
+          `AnyOf is missing in the second schema at ${path.join(".")}`,
+        );
+      } else {
+        if (schema1.anyOf.length !== schema2.anyOf.length) {
+          differences.push(`AnyOf count mismatch at ${path.join(".")}`);
+        } else {
+          for (let i = 0; i < schema1.anyOf.length; i++) {
+            differences.push(
+              ...compare(schema1.anyOf[i], schema2.anyOf[i], [
+                ...path,
+                `[anyOf][${i}]`,
+              ]),
+            );
+          }
+        }
+      }
+    }
+    return differences;
+  }
+  return compare(schema1, schema2, []);
+}
+
+async function run() {
+  const [platform, software] = await Promise.all([
+    loadOpenApiDocument(JIRA_PLATFORM_API_URL),
+    loadOpenApiDocument(JIRA_SOFTWARE_API_URL),
+  ]);
+  const platformSchemas = platform.components!.schemas!;
+  const softwareSchemas = software.components!.schemas!;
+  let hasDifferences = false;
+  for (const [name, schema] of Object.entries(platformSchemas)) {
+    // Check schemas with the same name.
+    if (softwareSchemas[name] !== undefined) {
+      const differences = compareSchemaTypes(
+        schema,
+        softwareSchemas[name],
+        platform,
+        software,
+      );
+      if (differences.length > 0) {
+        hasDifferences = true;
+        console.error(`Schema ${name} has differences:`);
+        for (const difference of differences) {
+          console.error(`  ${difference}`);
+        }
+      }
+    }
+  }
+  if (hasDifferences) {
+    console.error("Schemas are different, exiting with status 1.");
+    process.exit(1);
+  } else {
+    // eslint-disable-next-line no-console
+    console.log(
+      "Great news, JIRA platform and software schemas are compatible!",
+    );
+  }
+}
+
+run().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/lib/index.d.ts

@@ -0,0 +1,15 @@
+import { type ApiClientAceOptions, type ApiClientApOptions, type ApiClientForgeApiExternalOptions, type ApiClientForgeApiOptions, type JiraApiClientForgeBridgeOptions } from "@resolution/atlassian-api-common";
+import { BaseJiraPlatformApiClient } from "./openapi/platform/base-jira-platform-api-client";
+import { BaseJiraSoftwareApiClient } from "./openapi/software/base-jira-software-api-client";
+export declare class JiraPlatformApi extends BaseJiraPlatformApiClient {
+    protected options: ApiClientForgeApiOptions | ApiClientForgeApiExternalOptions | JiraApiClientForgeBridgeOptions | ApiClientAceOptions | ApiClientApOptions;
+    constructor(options: ApiClientForgeApiOptions | ApiClientForgeApiExternalOptions | JiraApiClientForgeBridgeOptions | ApiClientAceOptions | ApiClientApOptions);
+    asApp: () => JiraPlatformApi;
+    asUser: (userAccountId: string) => JiraPlatformApi;
+}
+export declare class JiraSoftwareApi extends BaseJiraSoftwareApiClient {
+    protected options: ApiClientForgeApiOptions | ApiClientForgeApiExternalOptions | JiraApiClientForgeBridgeOptions | ApiClientAceOptions | ApiClientApOptions;
+    constructor(options: ApiClientForgeApiOptions | ApiClientForgeApiExternalOptions | JiraApiClientForgeBridgeOptions | ApiClientAceOptions | ApiClientApOptions);
+    asApp: () => JiraSoftwareApi;
+    asUser: (userAccountId: string) => JiraSoftwareApi;
+}

package/lib/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JiraSoftwareApi = exports.JiraPlatformApi = void 0;
+const atlassian_api_common_1 = require("@resolution/atlassian-api-common");
+const base_jira_platform_api_client_1 = require("./openapi/platform/base-jira-platform-api-client");
+const base_jira_software_api_client_1 = require("./openapi/software/base-jira-software-api-client");
+class JiraPlatformApi extends base_jira_platform_api_client_1.BaseJiraPlatformApiClient {
+    constructor(options) {
+        super((0, atlassian_api_common_1.getApiClientOptions)(options));
+        this.options = options;
+        this.asApp = (0, atlassian_api_common_1.createAsAppMethod)();
+        this.asUser = (0, atlassian_api_common_1.createAsUserMethod)();
+    }
+}
+exports.JiraPlatformApi = JiraPlatformApi;
+class JiraSoftwareApi extends base_jira_software_api_client_1.BaseJiraSoftwareApiClient {
+    constructor(options) {
+        super((0, atlassian_api_common_1.getApiClientOptions)(options));
+        this.options = options;
+        this.asApp = (0, atlassian_api_common_1.createAsAppMethod)();
+        this.asUser = (0, atlassian_api_common_1.createAsUserMethod)();
+    }
+}
+exports.JiraSoftwareApi = JiraSoftwareApi;
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,2EAS0C;AAE1C,oGAA6F;AAC7F,oGAA6F;AAE7F,MAAa,eAAgB,SAAQ,yDAAyB;IAC5D,YACY,OAKY;QAEtB,KAAK,CAAC,IAAA,0CAAmB,EAAC,OAAO,CAAC,CAAC,CAAC;QAP1B,YAAO,GAAP,OAAO,CAKK;QAIxB,UAAK,GAAG,IAAA,wCAAiB,GAA0B,CAAC;QACpD,WAAM,GAAG,IAAA,yCAAkB,GAA0B,CAAC;IAFtD,CAAC;CAGF;AAbD,0CAaC;AAED,MAAa,eAAgB,SAAQ,yDAAyB;IAC5D,YACY,OAKY;QAEtB,KAAK,CAAC,IAAA,0CAAmB,EAAC,OAAO,CAAC,CAAC,CAAC;QAP1B,YAAO,GAAP,OAAO,CAKK;QAIxB,UAAK,GAAG,IAAA,wCAAiB,GAA0B,CAAC;QACpD,WAAM,GAAG,IAAA,yCAAkB,GAA0B,CAAC;IAFtD,CAAC;CAGF;AAbD,0CAaC"}