@backstage-community/plugin-jenkins-common 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @backstage-community/plugin-jenkins-common
 
+## 0.14.0
+
+### Minor Changes
+
+- daa9057: Backstage version bump to v1.45.3
+
+## 0.13.0
+
+### Minor Changes
+
+- cac3437: Replace the deprecated `jenkins` NPM package with a built-in, light-weight client.
+
 ## 0.12.0
 
 ### Minor Changes

package/dist/client/buildApi.cjs.js

@@ -0,0 +1,34 @@
+'use strict';
+
+function createBuildApi(deps) {
+  const { normalizeJobName, request } = deps;
+  return {
+    /**
+     * Retrieves a build's JSON representation from Jenkins.
+     *
+     * @param name - A build name (string or segments).
+     * @param buildNumber - The build number to retrieve.
+     * @returns A `JenkinsBuild` object with metadata about the specified build.
+     */
+    get: async (name, buildNumber) => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/${buildNumber}/api/json`);
+    },
+    /**
+     * Retrieves a build's consoleText from Jenkins.
+     *
+     * @param name - A build name (string or segments).
+     * @param buildNumber - The build number to retrieve logs for.
+     * @returns The build's console output as plain text.
+     */
+    getConsoleText: async (name, buildNumber) => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/${buildNumber}/consoleText`, {
+        rawText: true
+      });
+    }
+  };
+}
+
+exports.createBuildApi = createBuildApi;
+//# sourceMappingURL=buildApi.cjs.js.map

package/dist/client/buildApi.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildApi.cjs.js","sources":["../../src/client/buildApi.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { JenkinsBuild } from '../types';\n\nexport interface BuildDeps {\n  normalizeJobName(string: string | string[] | undefined): string | undefined;\n  request(\n    path: string,\n    opts?: {\n      method?: string;\n      query?: Record<string, string | number | undefined>;\n      body?: any;\n      rawText?: boolean;\n      contentType?: string;\n    },\n  ): Promise<any>;\n}\n\n/**\n * Factory for creating a Jenkins Build API interface.\n *\n * Provides helpers for common Jenkins job operations such as:\n * - Fetching build details (`get`)\n * - Fetching build console output as plain text (`getConsoleText`)\n *\n * This function is intended to be used by higher-level clients (e.g., `Jenkins`)\n * and delegates low-level requests to the provided `request` dependency.\n *\n * @param deps - Dependency injection hooks for request handling and job name normalization.\n * @returns An object with methods for interacting with Jenkins builds.\n */\nexport function createBuildApi(deps: BuildDeps) {\n  const { normalizeJobName, request } = deps;\n\n  return {\n    /**\n     * Retrieves a build's JSON representation from Jenkins.\n     *\n     * @param name - A build name (string or segments).\n     * @param buildNumber - The build number to retrieve.\n     * @returns A `JenkinsBuild` object with metadata about the specified build.\n     */\n    get: async (\n      name: string | string[],\n      buildNumber: number | string,\n    ): Promise<JenkinsBuild> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/${buildNumber}/api/json`);\n    },\n\n    /**\n     * Retrieves a build's consoleText from Jenkins.\n     *\n     * @param name - A build name (string or segments).\n     * @param buildNumber - The build number to retrieve logs for.\n     * @returns The build's console output as plain text.\n     */\n    getConsoleText: async (\n      name: string | string[],\n      buildNumber: number | string,\n    ): Promise<string> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/${buildNumber}/consoleText`, {\n        rawText: true,\n      }) as Promise<string>;\n    },\n  };\n}\n"],"names":[],"mappings":";;AA4CO,SAAS,eAAe,IAAiB,EAAA;AAC9C,EAAM,MAAA,EAAE,gBAAkB,EAAA,OAAA,EAAY,GAAA,IAAA;AAEtC,EAAO,OAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAQL,GAAA,EAAK,OACH,IAAA,EACA,WAC0B,KAAA;AAC1B,MAAM,MAAA,OAAA,GAAU,iBAAiB,IAAI,CAAA;AACrC,MAAA,OAAO,OAAQ,CAAA,CAAA,EAAG,OAAO,CAAA,CAAA,EAAI,WAAW,CAAW,SAAA,CAAA,CAAA;AAAA,KACrD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IASA,cAAA,EAAgB,OACd,IAAA,EACA,WACoB,KAAA;AACpB,MAAM,MAAA,OAAA,GAAU,iBAAiB,IAAI,CAAA;AACrC,MAAA,OAAO,OAAQ,CAAA,CAAA,EAAG,OAAO,CAAA,CAAA,EAAI,WAAW,CAAgB,YAAA,CAAA,EAAA;AAAA,QACtD,OAAS,EAAA;AAAA,OACV,CAAA;AAAA;AACH,GACF;AACF;;;;"}

package/dist/client/buildApi.esm.js

@@ -0,0 +1,32 @@
+function createBuildApi(deps) {
+  const { normalizeJobName, request } = deps;
+  return {
+    /**
+     * Retrieves a build's JSON representation from Jenkins.
+     *
+     * @param name - A build name (string or segments).
+     * @param buildNumber - The build number to retrieve.
+     * @returns A `JenkinsBuild` object with metadata about the specified build.
+     */
+    get: async (name, buildNumber) => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/${buildNumber}/api/json`);
+    },
+    /**
+     * Retrieves a build's consoleText from Jenkins.
+     *
+     * @param name - A build name (string or segments).
+     * @param buildNumber - The build number to retrieve logs for.
+     * @returns The build's console output as plain text.
+     */
+    getConsoleText: async (name, buildNumber) => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/${buildNumber}/consoleText`, {
+        rawText: true
+      });
+    }
+  };
+}
+
+export { createBuildApi };
+//# sourceMappingURL=buildApi.esm.js.map

package/dist/client/buildApi.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildApi.esm.js","sources":["../../src/client/buildApi.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { JenkinsBuild } from '../types';\n\nexport interface BuildDeps {\n  normalizeJobName(string: string | string[] | undefined): string | undefined;\n  request(\n    path: string,\n    opts?: {\n      method?: string;\n      query?: Record<string, string | number | undefined>;\n      body?: any;\n      rawText?: boolean;\n      contentType?: string;\n    },\n  ): Promise<any>;\n}\n\n/**\n * Factory for creating a Jenkins Build API interface.\n *\n * Provides helpers for common Jenkins job operations such as:\n * - Fetching build details (`get`)\n * - Fetching build console output as plain text (`getConsoleText`)\n *\n * This function is intended to be used by higher-level clients (e.g., `Jenkins`)\n * and delegates low-level requests to the provided `request` dependency.\n *\n * @param deps - Dependency injection hooks for request handling and job name normalization.\n * @returns An object with methods for interacting with Jenkins builds.\n */\nexport function createBuildApi(deps: BuildDeps) {\n  const { normalizeJobName, request } = deps;\n\n  return {\n    /**\n     * Retrieves a build's JSON representation from Jenkins.\n     *\n     * @param name - A build name (string or segments).\n     * @param buildNumber - The build number to retrieve.\n     * @returns A `JenkinsBuild` object with metadata about the specified build.\n     */\n    get: async (\n      name: string | string[],\n      buildNumber: number | string,\n    ): Promise<JenkinsBuild> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/${buildNumber}/api/json`);\n    },\n\n    /**\n     * Retrieves a build's consoleText from Jenkins.\n     *\n     * @param name - A build name (string or segments).\n     * @param buildNumber - The build number to retrieve logs for.\n     * @returns The build's console output as plain text.\n     */\n    getConsoleText: async (\n      name: string | string[],\n      buildNumber: number | string,\n    ): Promise<string> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/${buildNumber}/consoleText`, {\n        rawText: true,\n      }) as Promise<string>;\n    },\n  };\n}\n"],"names":[],"mappings":"AA4CO,SAAS,eAAe,IAAiB,EAAA;AAC9C,EAAM,MAAA,EAAE,gBAAkB,EAAA,OAAA,EAAY,GAAA,IAAA;AAEtC,EAAO,OAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAQL,GAAA,EAAK,OACH,IAAA,EACA,WAC0B,KAAA;AAC1B,MAAM,MAAA,OAAA,GAAU,iBAAiB,IAAI,CAAA;AACrC,MAAA,OAAO,OAAQ,CAAA,CAAA,EAAG,OAAO,CAAA,CAAA,EAAI,WAAW,CAAW,SAAA,CAAA,CAAA;AAAA,KACrD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IASA,cAAA,EAAgB,OACd,IAAA,EACA,WACoB,KAAA;AACpB,MAAM,MAAA,OAAA,GAAU,iBAAiB,IAAI,CAAA;AACrC,MAAA,OAAO,OAAQ,CAAA,CAAA,EAAG,OAAO,CAAA,CAAA,EAAI,WAAW,CAAgB,YAAA,CAAA,EAAA;AAAA,QACtD,OAAS,EAAA;AAAA,OACV,CAAA;AAAA;AACH,GACF;AACF;;;;"}

package/dist/client/jobApi.cjs.js

@@ -0,0 +1,180 @@
+'use strict';
+
+function createJobApi(deps) {
+  const { normalizeJobName, request } = deps;
+  const paramsToSearchParams = (params) => {
+    if (!params) {
+      return new URLSearchParams();
+    }
+    if (params instanceof URLSearchParams) {
+      return params;
+    }
+    const result = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v === void 0 || v === null) {
+        continue;
+      }
+      result.set(k, String(v));
+    }
+    return result;
+  };
+  const leafSegment = (name) => {
+    if (Array.isArray(name)) {
+      return name[name.length - 1];
+    }
+    const parts = name.split("/").filter(Boolean);
+    return parts[parts.length - 1] ?? "";
+  };
+  const parentSegments = (name) => {
+    if (!name) {
+      return [];
+    }
+    if (Array.isArray(name)) {
+      return name.slice(0, -1);
+    }
+    const parts = name.split("/").filter(Boolean);
+    if (parts.length > 1) {
+      return parts.slice(0, -1);
+    }
+    return [];
+  };
+  return {
+    /**
+     * Retrieves a job’s JSON representation from Jenkins.
+     *
+     * @param input - A {@link JobGetOptions} object. `tree` and `depth`
+     *                are forwarded to `/api/json` as query params.
+     * @returns The parsed job JSON.
+     */
+    get: async (input) => {
+      const { name, tree, depth } = input;
+      const jobPath = normalizeJobName(name);
+      const query = {};
+      if (tree) {
+        query.tree = tree;
+      }
+      if (typeof depth === "number") {
+        query.depth = depth;
+      }
+      return request(`${jobPath}/api/json`, { query });
+    },
+    /**
+     * Retrieves only the builds portion of a job (server-side filtered via `tree`).
+     *
+     * @param name - The job name (string or array).
+     * @param tree - The Jenkins Remote API `tree` expression selecting build fields.
+     *               Defaults to `builds[number,url,result,timestamp,id,queueId,displayName,duration]`
+     * @returns A JSON object containing the requested build fields.
+     */
+    getBuilds: async (name, tree = "builds[number,url,result,timestamp,id,queueId,displayName,duration]") => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/api/json`, {
+        query: { tree }
+      });
+    },
+    /**
+     * Triggers a Jenkins job build.
+     *
+     * Uses `/build` or `/buildWithParameters` depending on whether parameters are provided.
+     * Automatically URL-encodes parameters and supports legacy options like `delay` and `token`.
+     *
+     * @param name - The job name (string or array form).
+     * @param opts - Optional build options (parameters, token, delay).
+     * @returns A promise that resolves when the build request is accepted.
+     */
+    build: async (name, opts) => {
+      const { parameters, token, delay } = opts ?? {};
+      const jobPath = normalizeJobName(name);
+      const hasParams = parameters instanceof URLSearchParams ? parameters.toString().length > 0 : parameters && Object.keys(parameters).length > 0;
+      const endpoint = hasParams ? "buildWithParameters" : "build";
+      const query = {
+        ...token ? { token } : {},
+        // Legacy client support: add delay option
+        ...delay !== void 0 ? { delay } : {}
+      };
+      const body = hasParams ? paramsToSearchParams(parameters) : void 0;
+      return request(`${jobPath}/${endpoint}`, {
+        method: "POST",
+        query,
+        body
+      });
+    },
+    /**
+     * Copies a job to a new name (optionally inside folders).
+     *
+     * **Important:** For the `from` argument, pass the *slashy* full name (e.g. `"a/b/src"`).
+     * Do **not** normalize it to `/job/...` form, Jenkins expects the raw slash-separated name.
+     * Only the *leaf* of the new job goes in the `?name=` query; parent folders are derived
+     * from `name` and embedded in the URL path.
+     *
+     * @param name - Target job name (string or segments). Parent parts become folders; leaf is the new job name.
+     * @param from - Source job’s slashy full name (e.g. `"folder/old"`).
+     */
+    copy: async (name, from) => {
+      const segments = parentSegments(name);
+      const leaf = leafSegment(name);
+      const folderPath = segments.length ? segments.map(normalizeJobName).join("/") : "";
+      const url = folderPath ? `${folderPath}/createItem` : "createItem";
+      return request(url, {
+        method: "POST",
+        query: {
+          name: leaf,
+          mode: "copy",
+          from
+          // Keep slashy!
+        }
+      });
+    },
+    /**
+     * Creates a new job from an XML configuration payload.
+     *
+     * Only the *leaf* job name is sent in `?name=`; any parent segments become
+     * folder parts embedded in the URL path.
+     *
+     * @param name - The destination job name (string or segments).
+     * @param xml - The Jenkins job config.xml content.
+     */
+    create: async (name, xml) => {
+      const segments = parentSegments(name);
+      const leaf = leafSegment(name);
+      const folderPath = segments.length ? segments.map(normalizeJobName).join("/") : "";
+      const url = folderPath ? `${folderPath}/createItem` : "createItem";
+      return request(url, {
+        method: "POST",
+        query: { name: leaf },
+        body: xml,
+        contentType: "application/xml"
+      });
+    },
+    /**
+     * Permanently deletes a job.
+     *
+     * @param name - The job name (string or segments).
+     */
+    destroy: async (name) => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/doDelete`, { method: "POST" });
+    },
+    /**
+     * Enables a disabled job.
+     *
+     * @param name - The job name (string or segments).
+     */
+    enable: async (name) => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/enable`, { method: "POST" });
+    },
+    /**
+     * Disables a job (prevents builds from being scheduled).
+     *
+     * @param name - The job name (string or segments).
+     */
+    disable: async (name) => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/disable`, { method: "POST" });
+    }
+  };
+}
+
+exports.createJobApi = createJobApi;
+//# sourceMappingURL=jobApi.cjs.js.map

package/dist/client/jobApi.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobApi.cjs.js","sources":["../../src/client/jobApi.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { JenkinsParams, JobBuildOptions, JobGetOptions } from './types';\n\nexport interface JobDeps {\n  normalizeJobName(name: string | string[] | undefined): string | undefined;\n  request(\n    path: string,\n    opts?: {\n      method?: string;\n      query?: Record<string, string | number | undefined>;\n      body?: any;\n      rawText?: boolean;\n      contentType?: string;\n    },\n  ): Promise<any>;\n}\n\n/**\n * Factory for creating a Jenkins Job API interface.\n *\n * Provides helpers for common Jenkins job operations such as:\n * - Fetching job details (`get`)\n * - Triggering builds (`build`)\n * - Copying or creating jobs (`copy`, `create`)\n * - Managing job state (`enable`, `disable`, `destroy`)\n *\n * This function is intended to be used by higher-level clients (e.g., `Jenkins`)\n * and delegates low-level requests to the provided `request` dependency.\n *\n * @param deps - Dependency injection hooks for request handling and job name normalization.\n * @returns An object with methods for interacting with Jenkins jobs.\n */\nexport function createJobApi(deps: JobDeps) {\n  const { normalizeJobName, request } = deps;\n\n  // Helper utils\n\n  /**\n   * Takes in a {@link JenkinsParams} object and returns a {@link URLSearchParams} object.\n   *   - If the object passed is `undefined`, an empty {@link URLSearchParams} is returned.\n   *   - If the object passed is already a {@link URLSearchParams} it gets returned as is.\n   *\n   * @param params a {@link JenkinsParams} object.\n   * @returns a {@link URLSearchParams} object\n   */\n  const paramsToSearchParams = (params?: JenkinsParams): URLSearchParams => {\n    if (!params) {\n      return new URLSearchParams();\n    }\n    if (params instanceof URLSearchParams) {\n      return params;\n    }\n\n    const result = new URLSearchParams();\n    for (const [k, v] of Object.entries(params)) {\n      if (v === undefined || v === null) {\n        continue;\n      }\n      result.set(k, String(v));\n    }\n    return result;\n  };\n\n  /**\n   * Extracts the last path segment (the \"leaf\" job name) from a Jenkins job name.\n   *\n   * @param name - The job name, either as a slash-delimited string (e.g. \"folder/job\")\n   *               or as an array of segments (e.g. [\"folder\", \"job\"]).\n   * @returns The last segment of the job name, or an empty string if none exists.\n   *\n   * @example\n   * leafSegment(\"folder/job\"); // \"job\"\n   * leafSegment([\"folder\", \"job\"]); // \"job\"\n   * leafSegment(\"root\"); // \"root\"\n   */\n  const leafSegment = (name: string | string[]): string => {\n    if (Array.isArray(name)) {\n      return name[name.length - 1];\n    }\n    const parts = name.split('/').filter(Boolean);\n    return parts[parts.length - 1] ?? '';\n  };\n\n  /**\n   * Returns all parent path segments of a Jenkins job name, excluding the leaf.\n   *\n   * @param name - The job name, either as a slash-delimited string (e.g. \"a/b/c\")\n   *               or as an array of segments (e.g. [\"a\", \"b\", \"c\"]).\n   * @returns An array of all parent segments, or an empty array if the job is at the root.\n   *\n   * @example\n   * parentSegments(\"a/b/c\"); // [\"a\", \"b\"]\n   * parentSegments([\"a\", \"b\", \"c\"]); // [\"a\", \"b\"]\n   * parentSegments(\"job\"); // []\n   */\n  const parentSegments = (name: string | string[] | undefined): string[] => {\n    if (!name) {\n      return [];\n    }\n\n    // Return everything but leaf\n    if (Array.isArray(name)) {\n      return name.slice(0, -1);\n    }\n\n    const parts = name.split('/').filter(Boolean);\n    if (parts.length > 1) {\n      return parts.slice(0, -1);\n    }\n\n    return [];\n  };\n\n  return {\n    /**\n     * Retrieves a job’s JSON representation from Jenkins.\n     *\n     * @param input - A {@link JobGetOptions} object. `tree` and `depth`\n     *                are forwarded to `/api/json` as query params.\n     * @returns The parsed job JSON.\n     */\n    get: async (input: JobGetOptions) => {\n      const { name, tree, depth } = input;\n      const jobPath = normalizeJobName(name);\n      const query: Record<string, string | number> = {};\n      if (tree) {\n        query.tree = tree;\n      }\n      if (typeof depth === 'number') {\n        query.depth = depth;\n      }\n      return request(`${jobPath}/api/json`, { query });\n    },\n\n    /**\n     * Retrieves only the builds portion of a job (server-side filtered via `tree`).\n     *\n     * @param name - The job name (string or array).\n     * @param tree - The Jenkins Remote API `tree` expression selecting build fields.\n     *               Defaults to `builds[number,url,result,timestamp,id,queueId,displayName,duration]`\n     * @returns A JSON object containing the requested build fields.\n     */\n    getBuilds: async (\n      name: string | string[],\n      tree = 'builds[number,url,result,timestamp,id,queueId,displayName,duration]',\n    ): Promise<unknown> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/api/json`, {\n        query: { tree },\n      });\n    },\n\n    /**\n     * Triggers a Jenkins job build.\n     *\n     * Uses `/build` or `/buildWithParameters` depending on whether parameters are provided.\n     * Automatically URL-encodes parameters and supports legacy options like `delay` and `token`.\n     *\n     * @param name - The job name (string or array form).\n     * @param opts - Optional build options (parameters, token, delay).\n     * @returns A promise that resolves when the build request is accepted.\n     */\n    build: async (\n      name: string | string[],\n      opts?: JobBuildOptions,\n    ): Promise<unknown> => {\n      const { parameters, token, delay } = opts ?? {};\n\n      const jobPath = normalizeJobName(name);\n\n      // Check if we have search params\n      // This will determine the endpoint used\n      const hasParams =\n        parameters instanceof URLSearchParams\n          ? parameters.toString().length > 0\n          : parameters && Object.keys(parameters).length > 0;\n\n      const endpoint = hasParams ? 'buildWithParameters' : 'build';\n\n      const query: Record<string, string> = {\n        ...(token ? { token } : {}),\n        // Legacy client support: add delay option\n        ...(delay !== undefined ? { delay } : {}),\n      };\n\n      const body: URLSearchParams | undefined = hasParams\n        ? paramsToSearchParams(parameters)\n        : undefined;\n\n      return request(`${jobPath}/${endpoint}`, {\n        method: 'POST',\n        query,\n        body,\n      });\n    },\n\n    /**\n     * Copies a job to a new name (optionally inside folders).\n     *\n     * **Important:** For the `from` argument, pass the *slashy* full name (e.g. `\"a/b/src\"`).\n     * Do **not** normalize it to `/job/...` form, Jenkins expects the raw slash-separated name.\n     * Only the *leaf* of the new job goes in the `?name=` query; parent folders are derived\n     * from `name` and embedded in the URL path.\n     *\n     * @param name - Target job name (string or segments). Parent parts become folders; leaf is the new job name.\n     * @param from - Source job’s slashy full name (e.g. `\"folder/old\"`).\n     */\n    copy: async (name: string | string[], from: string): Promise<void> => {\n      const segments = parentSegments(name);\n      const leaf = leafSegment(name);\n      const folderPath = segments.length\n        ? segments.map(normalizeJobName).join('/')\n        : '';\n\n      const url = folderPath ? `${folderPath}/createItem` : 'createItem';\n      return request(url, {\n        method: 'POST',\n        query: {\n          name: leaf,\n          mode: 'copy',\n          from: from, // Keep slashy!\n        },\n      });\n    },\n\n    /**\n     * Creates a new job from an XML configuration payload.\n     *\n     * Only the *leaf* job name is sent in `?name=`; any parent segments become\n     * folder parts embedded in the URL path.\n     *\n     * @param name - The destination job name (string or segments).\n     * @param xml - The Jenkins job config.xml content.\n     */\n    create: async (name: string | string[], xml: string): Promise<void> => {\n      const segments = parentSegments(name);\n      const leaf = leafSegment(name);\n      const folderPath = segments.length\n        ? segments.map(normalizeJobName).join('/')\n        : '';\n\n      const url = folderPath ? `${folderPath}/createItem` : 'createItem';\n\n      return request(url, {\n        method: 'POST',\n        query: { name: leaf },\n        body: xml,\n        contentType: 'application/xml',\n      });\n    },\n\n    /**\n     * Permanently deletes a job.\n     *\n     * @param name - The job name (string or segments).\n     */\n    destroy: async (name: string | string[]): Promise<void> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/doDelete`, { method: 'POST' });\n    },\n\n    /**\n     * Enables a disabled job.\n     *\n     * @param name - The job name (string or segments).\n     */\n    enable: async (name: string | string[]): Promise<void> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/enable`, { method: 'POST' });\n    },\n\n    /**\n     * Disables a job (prevents builds from being scheduled).\n     *\n     * @param name - The job name (string or segments).\n     */\n    disable: async (name: string | string[]): Promise<void> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/disable`, { method: 'POST' });\n    },\n  };\n}\n"],"names":[],"mappings":";;AA+CO,SAAS,aAAa,IAAe,EAAA;AAC1C,EAAM,MAAA,EAAE,gBAAkB,EAAA,OAAA,EAAY,GAAA,IAAA;AAYtC,EAAM,MAAA,oBAAA,GAAuB,CAAC,MAA4C,KAAA;AACxE,IAAA,IAAI,CAAC,MAAQ,EAAA;AACX,MAAA,OAAO,IAAI,eAAgB,EAAA;AAAA;AAE7B,IAAA,IAAI,kBAAkB,eAAiB,EAAA;AACrC,MAAO,OAAA,MAAA;AAAA;AAGT,IAAM,MAAA,MAAA,GAAS,IAAI,eAAgB,EAAA;AACnC,IAAA,KAAA,MAAW,CAAC,CAAG,EAAA,CAAC,KAAK,MAAO,CAAA,OAAA,CAAQ,MAAM,CAAG,EAAA;AAC3C,MAAI,IAAA,CAAA,KAAM,KAAa,CAAA,IAAA,CAAA,KAAM,IAAM,EAAA;AACjC,QAAA;AAAA;AAEF,MAAA,MAAA,CAAO,GAAI,CAAA,CAAA,EAAG,MAAO,CAAA,CAAC,CAAC,CAAA;AAAA;AAEzB,IAAO,OAAA,MAAA;AAAA,GACT;AAcA,EAAM,MAAA,WAAA,GAAc,CAAC,IAAoC,KAAA;AACvD,IAAI,IAAA,KAAA,CAAM,OAAQ,CAAA,IAAI,CAAG,EAAA;AACvB,MAAO,OAAA,IAAA,CAAK,IAAK,CAAA,MAAA,GAAS,CAAC,CAAA;AAAA;AAE7B,IAAA,MAAM,QAAQ,IAAK,CAAA,KAAA,CAAM,GAAG,CAAA,CAAE,OAAO,OAAO,CAAA;AAC5C,IAAA,OAAO,KAAM,CAAA,KAAA,CAAM,MAAS,GAAA,CAAC,CAAK,IAAA,EAAA;AAAA,GACpC;AAcA,EAAM,MAAA,cAAA,GAAiB,CAAC,IAAkD,KAAA;AACxE,IAAA,IAAI,CAAC,IAAM,EAAA;AACT,MAAA,OAAO,EAAC;AAAA;AAIV,IAAI,IAAA,KAAA,CAAM,OAAQ,CAAA,IAAI,CAAG,EAAA;AACvB,MAAO,OAAA,IAAA,CAAK,KAAM,CAAA,CAAA,EAAG,CAAE,CAAA,CAAA;AAAA;AAGzB,IAAA,MAAM,QAAQ,IAAK,CAAA,KAAA,CAAM,GAAG,CAAA,CAAE,OAAO,OAAO,CAAA;AAC5C,IAAI,IAAA,KAAA,CAAM,SAAS,CAAG,EAAA;AACpB,MAAO,OAAA,KAAA,CAAM,KAAM,CAAA,CAAA,EAAG,CAAE,CAAA,CAAA;AAAA;AAG1B,IAAA,OAAO,EAAC;AAAA,GACV;AAEA,EAAO,OAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAQL,GAAA,EAAK,OAAO,KAAyB,KAAA;AACnC,MAAA,MAAM,EAAE,IAAA,EAAM,IAAM,EAAA,KAAA,EAAU,GAAA,KAAA;AAC9B,MAAM,MAAA,OAAA,GAAU,iBAAiB,IAAI,CAAA;AACrC,MAAA,MAAM,QAAyC,EAAC;AAChD,MAAA,IAAI,IAAM,EAAA;AACR,QAAA,KAAA,CAAM,IAAO,GAAA,IAAA;AAAA;AAEf,MAAI,IAAA,OAAO,UAAU,QAAU,EAAA;AAC7B,QAAA,KAAA,CAAM,KAAQ,GAAA,KAAA;AAAA;AAEhB,MAAA,OAAO,QAAQ,CAAG,EAAA,OAAO,CAAa,SAAA,CAAA,EAAA,EAAE,OAAO,CAAA;AAAA,KACjD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAUA,SAAW,EAAA,OACT,IACA,EAAA,IAAA,GAAO,qEACc,KAAA;AACrB,MAAM,MAAA,OAAA,GAAU,iBAAiB,IAAI,CAAA;AACrC,MAAO,OAAA,OAAA,CAAQ,CAAG,EAAA,OAAO,CAAa,SAAA,CAAA,EAAA;AAAA,QACpC,KAAA,EAAO,EAAE,IAAK;AAAA,OACf,CAAA;AAAA,KACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAYA,KAAA,EAAO,OACL,IAAA,EACA,IACqB,KAAA;AACrB,MAAA,MAAM,EAAE,UAAY,EAAA,KAAA,EAAO,KAAM,EAAA,GAAI,QAAQ,EAAC;AAE9C,MAAM,MAAA,OAAA,GAAU,iBAAiB,IAAI,CAAA;AAIrC,MAAA,MAAM,SACJ,GAAA,UAAA,YAAsB,eAClB,GAAA,UAAA,CAAW,QAAS,EAAA,CAAE,MAAS,GAAA,CAAA,GAC/B,UAAc,IAAA,MAAA,CAAO,IAAK,CAAA,UAAU,EAAE,MAAS,GAAA,CAAA;AAErD,MAAM,MAAA,QAAA,GAAW,YAAY,qBAAwB,GAAA,OAAA;AAErD,MAAA,MAAM,KAAgC,GAAA;AAAA,QACpC,GAAI,KAAA,GAAQ,EAAE,KAAA,KAAU,EAAC;AAAA;AAAA,QAEzB,GAAI,KAAU,KAAA,KAAA,CAAA,GAAY,EAAE,KAAA,KAAU;AAAC,OACzC;AAEA,MAAA,MAAM,IAAoC,GAAA,SAAA,GACtC,oBAAqB,CAAA,UAAU,CAC/B,GAAA,KAAA,CAAA;AAEJ,MAAA,OAAO,OAAQ,CAAA,CAAA,EAAG,OAAO,CAAA,CAAA,EAAI,QAAQ,CAAI,CAAA,EAAA;AAAA,QACvC,MAAQ,EAAA,MAAA;AAAA,QACR,KAAA;AAAA,QACA;AAAA,OACD,CAAA;AAAA,KACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAaA,IAAA,EAAM,OAAO,IAAA,EAAyB,IAAgC,KAAA;AACpE,MAAM,MAAA,QAAA,GAAW,eAAe,IAAI,CAAA;AACpC,MAAM,MAAA,IAAA,GAAO,YAAY,IAAI,CAAA;AAC7B,MAAM,MAAA,UAAA,GAAa,SAAS,MACxB,GAAA,QAAA,CAAS,IAAI,gBAAgB,CAAA,CAAE,IAAK,CAAA,GAAG,CACvC,GAAA,EAAA;AAEJ,MAAA,MAAM,GAAM,GAAA,UAAA,GAAa,CAAG,EAAA,UAAU,CAAgB,WAAA,CAAA,GAAA,YAAA;AACtD,MAAA,OAAO,QAAQ,GAAK,EAAA;AAAA,QAClB,MAAQ,EAAA,MAAA;AAAA,QACR,KAAO,EAAA;AAAA,UACL,IAAM,EAAA,IAAA;AAAA,UACN,IAAM,EAAA,MAAA;AAAA,UACN;AAAA;AAAA;AACF,OACD,CAAA;AAAA,KACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAWA,MAAA,EAAQ,OAAO,IAAA,EAAyB,GAA+B,KAAA;AACrE,MAAM,MAAA,QAAA,GAAW,eAAe,IAAI,CAAA;AACpC,MAAM,MAAA,IAAA,GAAO,YAAY,IAAI,CAAA;AAC7B,MAAM,MAAA,UAAA,GAAa,SAAS,MACxB,GAAA,QAAA,CAAS,IAAI,gBAAgB,CAAA,CAAE,IAAK,CAAA,GAAG,CACvC,GAAA,EAAA;AAEJ,MAAA,MAAM,GAAM,GAAA,UAAA,GAAa,CAAG,EAAA,UAAU,CAAgB,WAAA,CAAA,GAAA,YAAA;AAEtD,MAAA,OAAO,QAAQ,GAAK,EAAA;AAAA,QAClB,MAAQ,EAAA,MAAA;AAAA,QACR,KAAA,EAAO,EAAE,IAAA,EAAM,IAAK,EAAA;AAAA,QACpB,IAAM,EAAA,GAAA;AAAA,QACN,WAAa,EAAA;AAAA,OACd,CAAA;AAAA,KACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOA,OAAA,EAAS,OAAO,IAA2C,KAAA;AACzD,MAAM,MAAA,OAAA,GAAU,iBAAiB,IAAI,CAAA;AACrC,MAAA,OAAO,QAAQ,CAAG,EAAA,OAAO,aAAa,EAAE,MAAA,EAAQ,QAAQ,CAAA;AAAA,KAC1D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOA,MAAA,EAAQ,OAAO,IAA2C,KAAA;AACxD,MAAM,MAAA,OAAA,GAAU,iBAAiB,IAAI,CAAA;AACrC,MAAA,OAAO,QAAQ,CAAG,EAAA,OAAO,WAAW,EAAE,MAAA,EAAQ,QAAQ,CAAA;AAAA,KACxD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOA,OAAA,EAAS,OAAO,IAA2C,KAAA;AACzD,MAAM,MAAA,OAAA,GAAU,iBAAiB,IAAI,CAAA;AACrC,MAAA,OAAO,QAAQ,CAAG,EAAA,OAAO,YAAY,EAAE,MAAA,EAAQ,QAAQ,CAAA;AAAA;AACzD,GACF;AACF;;;;"}

package/dist/client/jobApi.esm.js

@@ -0,0 +1,178 @@
+function createJobApi(deps) {
+  const { normalizeJobName, request } = deps;
+  const paramsToSearchParams = (params) => {
+    if (!params) {
+      return new URLSearchParams();
+    }
+    if (params instanceof URLSearchParams) {
+      return params;
+    }
+    const result = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v === void 0 || v === null) {
+        continue;
+      }
+      result.set(k, String(v));
+    }
+    return result;
+  };
+  const leafSegment = (name) => {
+    if (Array.isArray(name)) {
+      return name[name.length - 1];
+    }
+    const parts = name.split("/").filter(Boolean);
+    return parts[parts.length - 1] ?? "";
+  };
+  const parentSegments = (name) => {
+    if (!name) {
+      return [];
+    }
+    if (Array.isArray(name)) {
+      return name.slice(0, -1);
+    }
+    const parts = name.split("/").filter(Boolean);
+    if (parts.length > 1) {
+      return parts.slice(0, -1);
+    }
+    return [];
+  };
+  return {
+    /**
+     * Retrieves a job’s JSON representation from Jenkins.
+     *
+     * @param input - A {@link JobGetOptions} object. `tree` and `depth`
+     *                are forwarded to `/api/json` as query params.
+     * @returns The parsed job JSON.
+     */
+    get: async (input) => {
+      const { name, tree, depth } = input;
+      const jobPath = normalizeJobName(name);
+      const query = {};
+      if (tree) {
+        query.tree = tree;
+      }
+      if (typeof depth === "number") {
+        query.depth = depth;
+      }
+      return request(`${jobPath}/api/json`, { query });
+    },
+    /**
+     * Retrieves only the builds portion of a job (server-side filtered via `tree`).
+     *
+     * @param name - The job name (string or array).
+     * @param tree - The Jenkins Remote API `tree` expression selecting build fields.
+     *               Defaults to `builds[number,url,result,timestamp,id,queueId,displayName,duration]`
+     * @returns A JSON object containing the requested build fields.
+     */
+    getBuilds: async (name, tree = "builds[number,url,result,timestamp,id,queueId,displayName,duration]") => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/api/json`, {
+        query: { tree }
+      });
+    },
+    /**
+     * Triggers a Jenkins job build.
+     *
+     * Uses `/build` or `/buildWithParameters` depending on whether parameters are provided.
+     * Automatically URL-encodes parameters and supports legacy options like `delay` and `token`.
+     *
+     * @param name - The job name (string or array form).
+     * @param opts - Optional build options (parameters, token, delay).
+     * @returns A promise that resolves when the build request is accepted.
+     */
+    build: async (name, opts) => {
+      const { parameters, token, delay } = opts ?? {};
+      const jobPath = normalizeJobName(name);
+      const hasParams = parameters instanceof URLSearchParams ? parameters.toString().length > 0 : parameters && Object.keys(parameters).length > 0;
+      const endpoint = hasParams ? "buildWithParameters" : "build";
+      const query = {
+        ...token ? { token } : {},
+        // Legacy client support: add delay option
+        ...delay !== void 0 ? { delay } : {}
+      };
+      const body = hasParams ? paramsToSearchParams(parameters) : void 0;
+      return request(`${jobPath}/${endpoint}`, {
+        method: "POST",
+        query,
+        body
+      });
+    },
+    /**
+     * Copies a job to a new name (optionally inside folders).
+     *
+     * **Important:** For the `from` argument, pass the *slashy* full name (e.g. `"a/b/src"`).
+     * Do **not** normalize it to `/job/...` form, Jenkins expects the raw slash-separated name.
+     * Only the *leaf* of the new job goes in the `?name=` query; parent folders are derived
+     * from `name` and embedded in the URL path.
+     *
+     * @param name - Target job name (string or segments). Parent parts become folders; leaf is the new job name.
+     * @param from - Source job’s slashy full name (e.g. `"folder/old"`).
+     */
+    copy: async (name, from) => {
+      const segments = parentSegments(name);
+      const leaf = leafSegment(name);
+      const folderPath = segments.length ? segments.map(normalizeJobName).join("/") : "";
+      const url = folderPath ? `${folderPath}/createItem` : "createItem";
+      return request(url, {
+        method: "POST",
+        query: {
+          name: leaf,
+          mode: "copy",
+          from
+          // Keep slashy!
+        }
+      });
+    },
+    /**
+     * Creates a new job from an XML configuration payload.
+     *
+     * Only the *leaf* job name is sent in `?name=`; any parent segments become
+     * folder parts embedded in the URL path.
+     *
+     * @param name - The destination job name (string or segments).
+     * @param xml - The Jenkins job config.xml content.
+     */
+    create: async (name, xml) => {
+      const segments = parentSegments(name);
+      const leaf = leafSegment(name);
+      const folderPath = segments.length ? segments.map(normalizeJobName).join("/") : "";
+      const url = folderPath ? `${folderPath}/createItem` : "createItem";
+      return request(url, {
+        method: "POST",
+        query: { name: leaf },
+        body: xml,
+        contentType: "application/xml"
+      });
+    },
+    /**
+     * Permanently deletes a job.
+     *
+     * @param name - The job name (string or segments).
+     */
+    destroy: async (name) => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/doDelete`, { method: "POST" });
+    },
+    /**
+     * Enables a disabled job.
+     *
+     * @param name - The job name (string or segments).
+     */
+    enable: async (name) => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/enable`, { method: "POST" });
+    },
+    /**
+     * Disables a job (prevents builds from being scheduled).
+     *
+     * @param name - The job name (string or segments).
+     */
+    disable: async (name) => {
+      const jobPath = normalizeJobName(name);
+      return request(`${jobPath}/disable`, { method: "POST" });
+    }
+  };
+}
+
+export { createJobApi };
+//# sourceMappingURL=jobApi.esm.js.map

package/dist/client/jobApi.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobApi.esm.js","sources":["../../src/client/jobApi.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { JenkinsParams, JobBuildOptions, JobGetOptions } from './types';\n\nexport interface JobDeps {\n  normalizeJobName(name: string | string[] | undefined): string | undefined;\n  request(\n    path: string,\n    opts?: {\n      method?: string;\n      query?: Record<string, string | number | undefined>;\n      body?: any;\n      rawText?: boolean;\n      contentType?: string;\n    },\n  ): Promise<any>;\n}\n\n/**\n * Factory for creating a Jenkins Job API interface.\n *\n * Provides helpers for common Jenkins job operations such as:\n * - Fetching job details (`get`)\n * - Triggering builds (`build`)\n * - Copying or creating jobs (`copy`, `create`)\n * - Managing job state (`enable`, `disable`, `destroy`)\n *\n * This function is intended to be used by higher-level clients (e.g., `Jenkins`)\n * and delegates low-level requests to the provided `request` dependency.\n *\n * @param deps - Dependency injection hooks for request handling and job name normalization.\n * @returns An object with methods for interacting with Jenkins jobs.\n */\nexport function createJobApi(deps: JobDeps) {\n  const { normalizeJobName, request } = deps;\n\n  // Helper utils\n\n  /**\n   * Takes in a {@link JenkinsParams} object and returns a {@link URLSearchParams} object.\n   *   - If the object passed is `undefined`, an empty {@link URLSearchParams} is returned.\n   *   - If the object passed is already a {@link URLSearchParams} it gets returned as is.\n   *\n   * @param params a {@link JenkinsParams} object.\n   * @returns a {@link URLSearchParams} object\n   */\n  const paramsToSearchParams = (params?: JenkinsParams): URLSearchParams => {\n    if (!params) {\n      return new URLSearchParams();\n    }\n    if (params instanceof URLSearchParams) {\n      return params;\n    }\n\n    const result = new URLSearchParams();\n    for (const [k, v] of Object.entries(params)) {\n      if (v === undefined || v === null) {\n        continue;\n      }\n      result.set(k, String(v));\n    }\n    return result;\n  };\n\n  /**\n   * Extracts the last path segment (the \"leaf\" job name) from a Jenkins job name.\n   *\n   * @param name - The job name, either as a slash-delimited string (e.g. \"folder/job\")\n   *               or as an array of segments (e.g. [\"folder\", \"job\"]).\n   * @returns The last segment of the job name, or an empty string if none exists.\n   *\n   * @example\n   * leafSegment(\"folder/job\"); // \"job\"\n   * leafSegment([\"folder\", \"job\"]); // \"job\"\n   * leafSegment(\"root\"); // \"root\"\n   */\n  const leafSegment = (name: string | string[]): string => {\n    if (Array.isArray(name)) {\n      return name[name.length - 1];\n    }\n    const parts = name.split('/').filter(Boolean);\n    return parts[parts.length - 1] ?? '';\n  };\n\n  /**\n   * Returns all parent path segments of a Jenkins job name, excluding the leaf.\n   *\n   * @param name - The job name, either as a slash-delimited string (e.g. \"a/b/c\")\n   *               or as an array of segments (e.g. [\"a\", \"b\", \"c\"]).\n   * @returns An array of all parent segments, or an empty array if the job is at the root.\n   *\n   * @example\n   * parentSegments(\"a/b/c\"); // [\"a\", \"b\"]\n   * parentSegments([\"a\", \"b\", \"c\"]); // [\"a\", \"b\"]\n   * parentSegments(\"job\"); // []\n   */\n  const parentSegments = (name: string | string[] | undefined): string[] => {\n    if (!name) {\n      return [];\n    }\n\n    // Return everything but leaf\n    if (Array.isArray(name)) {\n      return name.slice(0, -1);\n    }\n\n    const parts = name.split('/').filter(Boolean);\n    if (parts.length > 1) {\n      return parts.slice(0, -1);\n    }\n\n    return [];\n  };\n\n  return {\n    /**\n     * Retrieves a job’s JSON representation from Jenkins.\n     *\n     * @param input - A {@link JobGetOptions} object. `tree` and `depth`\n     *                are forwarded to `/api/json` as query params.\n     * @returns The parsed job JSON.\n     */\n    get: async (input: JobGetOptions) => {\n      const { name, tree, depth } = input;\n      const jobPath = normalizeJobName(name);\n      const query: Record<string, string | number> = {};\n      if (tree) {\n        query.tree = tree;\n      }\n      if (typeof depth === 'number') {\n        query.depth = depth;\n      }\n      return request(`${jobPath}/api/json`, { query });\n    },\n\n    /**\n     * Retrieves only the builds portion of a job (server-side filtered via `tree`).\n     *\n     * @param name - The job name (string or array).\n     * @param tree - The Jenkins Remote API `tree` expression selecting build fields.\n     *               Defaults to `builds[number,url,result,timestamp,id,queueId,displayName,duration]`\n     * @returns A JSON object containing the requested build fields.\n     */\n    getBuilds: async (\n      name: string | string[],\n      tree = 'builds[number,url,result,timestamp,id,queueId,displayName,duration]',\n    ): Promise<unknown> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/api/json`, {\n        query: { tree },\n      });\n    },\n\n    /**\n     * Triggers a Jenkins job build.\n     *\n     * Uses `/build` or `/buildWithParameters` depending on whether parameters are provided.\n     * Automatically URL-encodes parameters and supports legacy options like `delay` and `token`.\n     *\n     * @param name - The job name (string or array form).\n     * @param opts - Optional build options (parameters, token, delay).\n     * @returns A promise that resolves when the build request is accepted.\n     */\n    build: async (\n      name: string | string[],\n      opts?: JobBuildOptions,\n    ): Promise<unknown> => {\n      const { parameters, token, delay } = opts ?? {};\n\n      const jobPath = normalizeJobName(name);\n\n      // Check if we have search params\n      // This will determine the endpoint used\n      const hasParams =\n        parameters instanceof URLSearchParams\n          ? parameters.toString().length > 0\n          : parameters && Object.keys(parameters).length > 0;\n\n      const endpoint = hasParams ? 'buildWithParameters' : 'build';\n\n      const query: Record<string, string> = {\n        ...(token ? { token } : {}),\n        // Legacy client support: add delay option\n        ...(delay !== undefined ? { delay } : {}),\n      };\n\n      const body: URLSearchParams | undefined = hasParams\n        ? paramsToSearchParams(parameters)\n        : undefined;\n\n      return request(`${jobPath}/${endpoint}`, {\n        method: 'POST',\n        query,\n        body,\n      });\n    },\n\n    /**\n     * Copies a job to a new name (optionally inside folders).\n     *\n     * **Important:** For the `from` argument, pass the *slashy* full name (e.g. `\"a/b/src\"`).\n     * Do **not** normalize it to `/job/...` form, Jenkins expects the raw slash-separated name.\n     * Only the *leaf* of the new job goes in the `?name=` query; parent folders are derived\n     * from `name` and embedded in the URL path.\n     *\n     * @param name - Target job name (string or segments). Parent parts become folders; leaf is the new job name.\n     * @param from - Source job’s slashy full name (e.g. `\"folder/old\"`).\n     */\n    copy: async (name: string | string[], from: string): Promise<void> => {\n      const segments = parentSegments(name);\n      const leaf = leafSegment(name);\n      const folderPath = segments.length\n        ? segments.map(normalizeJobName).join('/')\n        : '';\n\n      const url = folderPath ? `${folderPath}/createItem` : 'createItem';\n      return request(url, {\n        method: 'POST',\n        query: {\n          name: leaf,\n          mode: 'copy',\n          from: from, // Keep slashy!\n        },\n      });\n    },\n\n    /**\n     * Creates a new job from an XML configuration payload.\n     *\n     * Only the *leaf* job name is sent in `?name=`; any parent segments become\n     * folder parts embedded in the URL path.\n     *\n     * @param name - The destination job name (string or segments).\n     * @param xml - The Jenkins job config.xml content.\n     */\n    create: async (name: string | string[], xml: string): Promise<void> => {\n      const segments = parentSegments(name);\n      const leaf = leafSegment(name);\n      const folderPath = segments.length\n        ? segments.map(normalizeJobName).join('/')\n        : '';\n\n      const url = folderPath ? `${folderPath}/createItem` : 'createItem';\n\n      return request(url, {\n        method: 'POST',\n        query: { name: leaf },\n        body: xml,\n        contentType: 'application/xml',\n      });\n    },\n\n    /**\n     * Permanently deletes a job.\n     *\n     * @param name - The job name (string or segments).\n     */\n    destroy: async (name: string | string[]): Promise<void> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/doDelete`, { method: 'POST' });\n    },\n\n    /**\n     * Enables a disabled job.\n     *\n     * @param name - The job name (string or segments).\n     */\n    enable: async (name: string | string[]): Promise<void> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/enable`, { method: 'POST' });\n    },\n\n    /**\n     * Disables a job (prevents builds from being scheduled).\n     *\n     * @param name - The job name (string or segments).\n     */\n    disable: async (name: string | string[]): Promise<void> => {\n      const jobPath = normalizeJobName(name);\n      return request(`${jobPath}/disable`, { method: 'POST' });\n    },\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/client/utils.cjs.js

@@ -0,0 +1,39 @@
+'use strict';
+
+function addQueryParams(u, q) {
+  const dup = new URL(u.toString());
+  for (const [k, v] of Object.entries(q)) {
+    if (v === void 0) {
+      continue;
+    }
+    dup.searchParams.set(k, String(v));
+  }
+  return dup;
+}
+function joinUrl(base, path) {
+  let dupBase = base;
+  if (!dupBase.endsWith("/")) {
+    dupBase += "/";
+  }
+  return dupBase + path;
+}
+function trimLeadingSlash(p) {
+  return p.startsWith("/") ? p.slice(1) : p;
+}
+function ensureTrailingSlash(u) {
+  return u.endsWith("/") ? u : `${u}/`;
+}
+async function safeExtractText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "<no response body>";
+  }
+}
+
+exports.addQueryParams = addQueryParams;
+exports.ensureTrailingSlash = ensureTrailingSlash;
+exports.joinUrl = joinUrl;
+exports.safeExtractText = safeExtractText;
+exports.trimLeadingSlash = trimLeadingSlash;
+//# sourceMappingURL=utils.cjs.js.map

package/dist/client/utils.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.cjs.js","sources":["../../src/client/utils.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { type Response } from 'node-fetch';\n\n/**\n * Copies the {@link URL} object passed, appends query params and returns the resulting {@link URL}.\n *\n * @param u The {@link URL} object that will be copied\n * @param q The {@link Record<string, string | number | undefined>} that stores query params\n * @returns The resulting {@link URL} with query params.\n */\nexport function addQueryParams(\n  u: URL,\n  q: Record<string, string | number | undefined>,\n): URL {\n  // Create duplicate of URL, do not mutate original\n  const dup = new URL(u.toString());\n  for (const [k, v] of Object.entries(q)) {\n    if (v === undefined) {\n      continue;\n    }\n    dup.searchParams.set(k, String(v));\n  }\n\n  return dup;\n}\n\n/**\n * Joins the base URL string with the specified path.\n * Appends a `/` to the end of the `base` if it doesn't already have it.\n *\n * @param base The base URL string\n * @param path The path that appends to the base string\n * @returns A string of the full URL\n */\nexport function joinUrl(base: string, path: string): string {\n  let dupBase = base;\n  if (!dupBase.endsWith('/')) {\n    dupBase += '/';\n  }\n  return dupBase + path;\n}\n\n/**\n * Utility function that removes the `/` from the start of a string if it exists.\n *\n * @param p The string to trim\n * @returns The string without the leading `/`\n */\nexport function trimLeadingSlash(p: string): string {\n  return p.startsWith('/') ? p.slice(1) : p;\n}\n\n/**\n * Utility function that ensures that string ends with `/`,\n *\n * @param u The string to modify\n * @returns The resulting string, ending with `/`\n */\nexport function ensureTrailingSlash(u: string): string {\n  return u.endsWith('/') ? u : `${u}/`;\n}\n\n/**\n * Utility function that safely extracts the text from a response.\n * If the operation results in an error a default string is returned instead.\n *\n * @param res The {@link Response} containing the `Body.text`\n * @returns The resulting `Body.text` value or a default string if the operation failed\n */\nexport async function safeExtractText(res: Response): Promise<string> {\n  try {\n    return await res.text();\n  } catch {\n    return '<no response body>';\n  }\n}\n"],"names":[],"mappings":";;AAwBgB,SAAA,cAAA,CACd,GACA,CACK,EAAA;AAEL,EAAA,MAAM,GAAM,GAAA,IAAI,GAAI,CAAA,CAAA,CAAE,UAAU,CAAA;AAChC,EAAA,KAAA,MAAW,CAAC,CAAG,EAAA,CAAC,KAAK,MAAO,CAAA,OAAA,CAAQ,CAAC,CAAG,EAAA;AACtC,IAAA,IAAI,MAAM,KAAW,CAAA,EAAA;AACnB,MAAA;AAAA;AAEF,IAAA,GAAA,CAAI,YAAa,CAAA,GAAA,CAAI,CAAG,EAAA,MAAA,CAAO,CAAC,CAAC,CAAA;AAAA;AAGnC,EAAO,OAAA,GAAA;AACT;AAUgB,SAAA,OAAA,CAAQ,MAAc,IAAsB,EAAA;AAC1D,EAAA,IAAI,OAAU,GAAA,IAAA;AACd,EAAA,IAAI,CAAC,OAAA,CAAQ,QAAS,CAAA,GAAG,CAAG,EAAA;AAC1B,IAAW,OAAA,IAAA,GAAA;AAAA;AAEb,EAAA,OAAO,OAAU,GAAA,IAAA;AACnB;AAQO,SAAS,iBAAiB,CAAmB,EAAA;AAClD,EAAA,OAAO,EAAE,UAAW,CAAA,GAAG,IAAI,CAAE,CAAA,KAAA,CAAM,CAAC,CAAI,GAAA,CAAA;AAC1C;AAQO,SAAS,oBAAoB,CAAmB,EAAA;AACrD,EAAA,OAAO,EAAE,QAAS,CAAA,GAAG,CAAI,GAAA,CAAA,GAAI,GAAG,CAAC,CAAA,CAAA,CAAA;AACnC;AASA,eAAsB,gBAAgB,GAAgC,EAAA;AACpE,EAAI,IAAA;AACF,IAAO,OAAA,MAAM,IAAI,IAAK,EAAA;AAAA,GAChB,CAAA,MAAA;AACN,IAAO,OAAA,oBAAA;AAAA;AAEX;;;;;;;;"}

package/dist/client/utils.esm.js

@@ -0,0 +1,33 @@
+function addQueryParams(u, q) {
+  const dup = new URL(u.toString());
+  for (const [k, v] of Object.entries(q)) {
+    if (v === void 0) {
+      continue;
+    }
+    dup.searchParams.set(k, String(v));
+  }
+  return dup;
+}
+function joinUrl(base, path) {
+  let dupBase = base;
+  if (!dupBase.endsWith("/")) {
+    dupBase += "/";
+  }
+  return dupBase + path;
+}
+function trimLeadingSlash(p) {
+  return p.startsWith("/") ? p.slice(1) : p;
+}
+function ensureTrailingSlash(u) {
+  return u.endsWith("/") ? u : `${u}/`;
+}
+async function safeExtractText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "<no response body>";
+  }
+}
+
+export { addQueryParams, ensureTrailingSlash, joinUrl, safeExtractText, trimLeadingSlash };
+//# sourceMappingURL=utils.esm.js.map

package/dist/client/utils.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.esm.js","sources":["../../src/client/utils.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport { type Response } from 'node-fetch';\n\n/**\n * Copies the {@link URL} object passed, appends query params and returns the resulting {@link URL}.\n *\n * @param u The {@link URL} object that will be copied\n * @param q The {@link Record<string, string | number | undefined>} that stores query params\n * @returns The resulting {@link URL} with query params.\n */\nexport function addQueryParams(\n  u: URL,\n  q: Record<string, string | number | undefined>,\n): URL {\n  // Create duplicate of URL, do not mutate original\n  const dup = new URL(u.toString());\n  for (const [k, v] of Object.entries(q)) {\n    if (v === undefined) {\n      continue;\n    }\n    dup.searchParams.set(k, String(v));\n  }\n\n  return dup;\n}\n\n/**\n * Joins the base URL string with the specified path.\n * Appends a `/` to the end of the `base` if it doesn't already have it.\n *\n * @param base The base URL string\n * @param path The path that appends to the base string\n * @returns A string of the full URL\n */\nexport function joinUrl(base: string, path: string): string {\n  let dupBase = base;\n  if (!dupBase.endsWith('/')) {\n    dupBase += '/';\n  }\n  return dupBase + path;\n}\n\n/**\n * Utility function that removes the `/` from the start of a string if it exists.\n *\n * @param p The string to trim\n * @returns The string without the leading `/`\n */\nexport function trimLeadingSlash(p: string): string {\n  return p.startsWith('/') ? p.slice(1) : p;\n}\n\n/**\n * Utility function that ensures that string ends with `/`,\n *\n * @param u The string to modify\n * @returns The resulting string, ending with `/`\n */\nexport function ensureTrailingSlash(u: string): string {\n  return u.endsWith('/') ? u : `${u}/`;\n}\n\n/**\n * Utility function that safely extracts the text from a response.\n * If the operation results in an error a default string is returned instead.\n *\n * @param res The {@link Response} containing the `Body.text`\n * @returns The resulting `Body.text` value or a default string if the operation failed\n */\nexport async function safeExtractText(res: Response): Promise<string> {\n  try {\n    return await res.text();\n  } catch {\n    return '<no response body>';\n  }\n}\n"],"names":[],"mappings":"AAwBgB,SAAA,cAAA,CACd,GACA,CACK,EAAA;AAEL,EAAA,MAAM,GAAM,GAAA,IAAI,GAAI,CAAA,CAAA,CAAE,UAAU,CAAA;AAChC,EAAA,KAAA,MAAW,CAAC,CAAG,EAAA,CAAC,KAAK,MAAO,CAAA,OAAA,CAAQ,CAAC,CAAG,EAAA;AACtC,IAAA,IAAI,MAAM,KAAW,CAAA,EAAA;AACnB,MAAA;AAAA;AAEF,IAAA,GAAA,CAAI,YAAa,CAAA,GAAA,CAAI,CAAG,EAAA,MAAA,CAAO,CAAC,CAAC,CAAA;AAAA;AAGnC,EAAO,OAAA,GAAA;AACT;AAUgB,SAAA,OAAA,CAAQ,MAAc,IAAsB,EAAA;AAC1D,EAAA,IAAI,OAAU,GAAA,IAAA;AACd,EAAA,IAAI,CAAC,OAAA,CAAQ,QAAS,CAAA,GAAG,CAAG,EAAA;AAC1B,IAAW,OAAA,IAAA,GAAA;AAAA;AAEb,EAAA,OAAO,OAAU,GAAA,IAAA;AACnB;AAQO,SAAS,iBAAiB,CAAmB,EAAA;AAClD,EAAA,OAAO,EAAE,UAAW,CAAA,GAAG,IAAI,CAAE,CAAA,KAAA,CAAM,CAAC,CAAI,GAAA,CAAA;AAC1C;AAQO,SAAS,oBAAoB,CAAmB,EAAA;AACrD,EAAA,OAAO,EAAE,QAAS,CAAA,GAAG,CAAI,GAAA,CAAA,GAAI,GAAG,CAAC,CAAA,CAAA,CAAA;AACnC;AASA,eAAsB,gBAAgB,GAAgC,EAAA;AACpE,EAAI,IAAA;AACF,IAAO,OAAA,MAAM,IAAI,IAAK,EAAA;AAAA,GAChB,CAAA,MAAA;AACN,IAAO,OAAA,oBAAA;AAAA;AAEX;;;;"}

package/dist/client.cjs.js

@@ -0,0 +1,180 @@
+'use strict';
+
+var fetch = require('node-fetch');
+var jobApi = require('./client/jobApi.cjs.js');
+var buildApi = require('./client/buildApi.cjs.js');
+var utils = require('./client/utils.cjs.js');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var fetch__default = /*#__PURE__*/_interopDefaultCompat(fetch);
+
+class Jenkins {
+  crumbData;
+  opts;
+  constructor(opts) {
+    if (!opts.baseUrl) {
+      throw new Error("Jenkins: opts.baseUrl is required");
+    }
+    if (opts.crumbIssuer === void 0) {
+      opts.crumbIssuer = true;
+    }
+    const referer = utils.ensureTrailingSlash(opts.baseUrl);
+    opts.headers = { referer, ...opts.headers ?? {} };
+    this.opts = opts;
+  }
+  // Add APIs
+  job = jobApi.createJobApi({
+    normalizeJobName: (name) => this.normalizeJobName(name),
+    request: (path, opts) => this.request(path, opts)
+  });
+  build = buildApi.createBuildApi({
+    normalizeJobName: (name) => this.normalizeJobName(name),
+    request: (path, opts) => this.request(path, opts)
+  });
+  /**
+   * Retrieves and caches the Jenkins CSRF protection crumb.
+   *
+   * Jenkins uses a "crumb" (similar to a CSRF token) to protect write operations
+   * such as POST requests. This method handles retrieving that crumb based on
+   * the client's configuration.
+   *
+   * Behavior:
+   * - If `crumbIssuer` is not enabled in the client options, it returns `undefined`.
+   * - If a cached crumb already exists, it is returned immediately.
+   * - If `crumbIssuer` is a function, that function is called to obtain the crumb.
+   * - Otherwise, it performs a network request to
+   *   `<baseUrl>/crumbIssuer/api/json` to fetch the crumb from Jenkins.
+   *
+   * The result is cached in `this.crumbData` for subsequent calls.
+   *
+   * @returns A `CrumbData` object containing the header name and value,
+   *          or `undefined` if no crumb issuer is configured or the request fails.
+   * @throws Any network or parsing errors that occur during the crumb fetch.
+   */
+  async getCrumb() {
+    const { crumbIssuer } = this.opts;
+    if (!crumbIssuer) {
+      return void 0;
+    }
+    if (this.crumbData) {
+      return this.crumbData;
+    }
+    if (typeof crumbIssuer === "function") {
+      this.crumbData = await crumbIssuer(this);
+      return this.crumbData;
+    }
+    const res = await this.fetchRaw(
+      `${utils.ensureTrailingSlash(this.opts.baseUrl)}crumbIssuer/api/json`
+    );
+    if (!res.ok) {
+      return void 0;
+    }
+    const data = await res.json();
+    this.crumbData = {
+      headerName: data.crumbRequestField,
+      headerValue: data.crumb
+    };
+    return this.crumbData;
+  }
+  async request(path, opts = {}) {
+    let url = new URL(
+      utils.joinUrl(utils.ensureTrailingSlash(this.opts.baseUrl), utils.trimLeadingSlash(path))
+    );
+    if (opts.query) {
+      url = utils.addQueryParams(url, opts.query);
+    }
+    const method = (opts?.method || (opts?.body ? "POST" : "GET")).toLocaleUpperCase("en-US");
+    const headers = {
+      ...this.opts.headers ?? {}
+    };
+    if (method !== "GET" && method !== "HEAD") {
+      const crumb = await this.getCrumb();
+      if (crumb) {
+        headers[crumb.headerName] = crumb.headerValue;
+        if (crumb.cookies?.length) {
+          const prior = typeof headers.cookie === "string" ? headers.cookie : "";
+          const extra = crumb.cookies.join("; ");
+          headers.cookie = prior ? `${prior}; ${extra}` : extra;
+        }
+      }
+    }
+    let resolvedContentType;
+    if (opts?.contentType) {
+      resolvedContentType = opts?.contentType;
+    }
+    if (!resolvedContentType && opts?.body instanceof URLSearchParams) {
+      resolvedContentType = "application/x-www-form-urlencoded; charset=UTF-8";
+    }
+    if (resolvedContentType) {
+      headers["content-type"] = resolvedContentType;
+    }
+    const res = await this.fetchRaw(url.toString(), {
+      method,
+      headers,
+      body: opts?.body
+    });
+    if (!res.ok) {
+      const text = await utils.safeExtractText(res);
+      throw new Error(
+        `Jenkins API error ${res.status} ${method} ${url.toString()}: ${text}`
+      );
+    }
+    if (opts?.rawText) {
+      return res.text();
+    }
+    const contentType = (res.headers.get("content-type") || "").toLocaleLowerCase("en-US");
+    if (contentType.includes("application/json")) {
+      return res.json();
+    }
+    return res.text();
+  }
+  async fetchRaw(input, init) {
+    const flattened = {};
+    for (const [k, v] of Object.entries(init?.headers ?? {})) {
+      if (Array.isArray(v)) {
+        flattened[k] = v.join(", ");
+      } else if (v === void 0) {
+        continue;
+      } else {
+        flattened[k] = v;
+      }
+    }
+    return fetch__default.default(input, {
+      ...init ?? {},
+      headers: flattened
+    });
+  }
+  /**
+   * Normalizes a Jenkins job name into a fully qualified job path.
+   *
+   * Jenkins job URLs use a hierarchical format like:
+   *   `/job/folder/job/subfolder/job/pipeline`
+   *
+   * This method takes a job name (either a string like `"folder/pipeline"`
+   * or an array like `["folder", "pipeline"]`) and converts it into the proper
+   * Jenkins API path format by inserting `job/` segments and URL-encoding
+   * each component.
+   *
+   * - If the input already contains `/job/` segments, it is returned as-is
+   *   (after trimming any leading slash).
+   * - If the input is undefined, an error is thrown.
+   *
+   * @param name - The job name to normalize, either as a string or an array of path segments.
+   * @returns The normalized Jenkins job path (e.g. `"job/folder/job/pipeline"`).
+   * @throws If the name is undefined or empty.
+   */
+  normalizeJobName(name) {
+    if (!name) {
+      throw new Error('Jenkins.normalizeJobName: "name" is required');
+    }
+    const parts = Array.isArray(name) ? name : name.split("/").filter(Boolean);
+    if (parts.join("/").includes("/job/")) {
+      return utils.trimLeadingSlash(Array.isArray(name) ? parts.join("/") : name);
+    }
+    return parts.map(encodeURIComponent).map((s) => `job/${s}`).join("/");
+  }
+}
+
+exports.Jenkins = Jenkins;
+//# sourceMappingURL=client.cjs.js.map

package/dist/client.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.cjs.js","sources":["../src/client.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport fetch from 'node-fetch';\nimport { createJobApi } from './client/jobApi';\nimport { createBuildApi } from './client/buildApi';\nimport { CrumbData, CrumbDataHeaderValues, HeaderValue } from './client/types';\n\nimport {\n  addQueryParams,\n  joinUrl,\n  trimLeadingSlash,\n  ensureTrailingSlash,\n  safeExtractText,\n} from './client/utils';\n\n/** @public */\nexport interface JenkinsClientOptions {\n  baseUrl: string; // e.g. \"https://jenkins.example.com\"\n  crumbIssuer?: boolean | ((client: any) => Promise<CrumbData>) | undefined;\n  headers?: Record<string, HeaderValue>;\n  promisify?: boolean; // For compatibility with old legacy API, not used.\n}\n\n/** @public */\nexport class Jenkins {\n  private crumbData?: CrumbData;\n  public readonly opts: JenkinsClientOptions;\n\n  constructor(opts: JenkinsClientOptions) {\n    if (!opts.baseUrl) {\n      throw new Error('Jenkins: opts.baseUrl is required');\n    }\n\n    // Legacy client behavior: set crumbIssuer to true if unset.\n    if (opts.crumbIssuer === undefined) {\n      opts.crumbIssuer = true;\n    }\n\n    // Legacy client behavior: set default headers and Referer\n    // The referer here is the baseUrl.\n    const referer = ensureTrailingSlash(opts.baseUrl);\n    opts.headers = { referer, ...(opts.headers ?? {}) };\n\n    this.opts = opts;\n  }\n\n  // Add APIs\n  job = createJobApi({\n    normalizeJobName: name => this.normalizeJobName(name),\n    request: (path, opts) => this.request(path, opts),\n  });\n\n  build = createBuildApi({\n    normalizeJobName: name => this.normalizeJobName(name),\n    request: (path, opts) => this.request(path, opts),\n  });\n\n  /**\n   * Retrieves and caches the Jenkins CSRF protection crumb.\n   *\n   * Jenkins uses a \"crumb\" (similar to a CSRF token) to protect write operations\n   * such as POST requests. This method handles retrieving that crumb based on\n   * the client's configuration.\n   *\n   * Behavior:\n   * - If `crumbIssuer` is not enabled in the client options, it returns `undefined`.\n   * - If a cached crumb already exists, it is returned immediately.\n   * - If `crumbIssuer` is a function, that function is called to obtain the crumb.\n   * - Otherwise, it performs a network request to\n   *   `<baseUrl>/crumbIssuer/api/json` to fetch the crumb from Jenkins.\n   *\n   * The result is cached in `this.crumbData` for subsequent calls.\n   *\n   * @returns A `CrumbData` object containing the header name and value,\n   *          or `undefined` if no crumb issuer is configured or the request fails.\n   * @throws Any network or parsing errors that occur during the crumb fetch.\n   */\n  private async getCrumb(): Promise<CrumbData | undefined> {\n    const { crumbIssuer } = this.opts;\n\n    if (!crumbIssuer) {\n      return undefined;\n    }\n\n    if (this.crumbData) {\n      return this.crumbData;\n    }\n\n    if (typeof crumbIssuer === 'function') {\n      this.crumbData = await crumbIssuer(this);\n      return this.crumbData;\n    }\n\n    // Fetch crumb from Jenkins\n    const res = await this.fetchRaw(\n      `${ensureTrailingSlash(this.opts.baseUrl)}crumbIssuer/api/json`,\n    );\n    if (!res.ok) {\n      return undefined;\n    }\n    const data = (await res.json()) as CrumbDataHeaderValues;\n    this.crumbData = {\n      headerName: data.crumbRequestField,\n      headerValue: data.crumb,\n    };\n\n    return this.crumbData;\n  }\n\n  private async request(\n    path: string,\n    opts: {\n      method?: string;\n      query?: Record<string, string | number | undefined>;\n      body?: any;\n      rawText?: boolean;\n      contentType?: string;\n    } = {},\n  ): Promise<any> {\n    let url = new URL(\n      joinUrl(ensureTrailingSlash(this.opts.baseUrl), trimLeadingSlash(path)),\n    );\n    if (opts.query) {\n      url = addQueryParams(url, opts.query);\n    }\n\n    const method = (\n      opts?.method || (opts?.body ? 'POST' : 'GET')\n    ).toLocaleUpperCase('en-US');\n    const headers: Record<string, HeaderValue> = {\n      ...(this.opts.headers ?? {}),\n    };\n\n    // Legacy client support: Add crumb if request is not read-only\n    if (method !== 'GET' && method !== 'HEAD') {\n      const crumb = await this.getCrumb();\n      if (crumb) {\n        headers[crumb.headerName] = crumb.headerValue;\n        // If the crumb call told us to include some cookies, merge them into\n        // the existing cookie header\n        if (crumb.cookies?.length) {\n          const prior =\n            typeof headers.cookie === 'string' ? headers.cookie : '';\n          const extra = crumb.cookies.join('; ');\n          headers.cookie = prior ? `${prior}; ${extra}` : extra;\n        }\n      }\n    }\n\n    // Set Content-Type, default to undefined if not set\n    // Check caller-specified content-type first\n    let resolvedContentType: string | undefined;\n    if (opts?.contentType) {\n      resolvedContentType = opts?.contentType;\n    }\n\n    // URLSearchParams -> x-www-form-urlencoded\n    if (!resolvedContentType && opts?.body instanceof URLSearchParams) {\n      resolvedContentType = 'application/x-www-form-urlencoded; charset=UTF-8';\n    }\n\n    if (resolvedContentType) {\n      headers['content-type'] = resolvedContentType;\n    }\n\n    const res = await this.fetchRaw(url.toString(), {\n      method,\n      headers,\n      body: opts?.body,\n    });\n\n    if (!res.ok) {\n      const text = await safeExtractText(res);\n      throw new Error(\n        `Jenkins API error ${res.status} ${method} ${url.toString()}: ${text}`,\n      );\n    }\n\n    if (opts?.rawText) {\n      return res.text();\n    }\n\n    const contentType = (\n      res.headers.get('content-type') || ''\n    ).toLocaleLowerCase('en-US');\n    if (contentType.includes('application/json')) {\n      return res.json();\n    }\n\n    return res.text();\n  }\n\n  private async fetchRaw(\n    input: string,\n    init?: {\n      method?: string;\n      headers?: Record<string, HeaderValue>;\n      body?: any;\n    },\n  ) {\n    // Flatten the values passed in \"headers\"\n    const flattened: Record<string, string> = {};\n    for (const [k, v] of Object.entries(init?.headers ?? {})) {\n      if (Array.isArray(v)) {\n        flattened[k] = v.join(', ');\n      } else if (v === undefined) {\n        continue;\n      } else {\n        flattened[k] = v;\n      }\n    }\n\n    return fetch(input, {\n      ...(init ?? {}),\n      headers: flattened as any,\n    });\n  }\n\n  /**\n   * Normalizes a Jenkins job name into a fully qualified job path.\n   *\n   * Jenkins job URLs use a hierarchical format like:\n   *   `/job/folder/job/subfolder/job/pipeline`\n   *\n   * This method takes a job name (either a string like `\"folder/pipeline\"`\n   * or an array like `[\"folder\", \"pipeline\"]`) and converts it into the proper\n   * Jenkins API path format by inserting `job/` segments and URL-encoding\n   * each component.\n   *\n   * - If the input already contains `/job/` segments, it is returned as-is\n   *   (after trimming any leading slash).\n   * - If the input is undefined, an error is thrown.\n   *\n   * @param name - The job name to normalize, either as a string or an array of path segments.\n   * @returns The normalized Jenkins job path (e.g. `\"job/folder/job/pipeline\"`).\n   * @throws If the name is undefined or empty.\n   */\n  private normalizeJobName(\n    name: string | string[] | undefined,\n  ): string | undefined {\n    if (!name) {\n      throw new Error('Jenkins.normalizeJobName: \"name\" is required');\n    }\n\n    const parts = Array.isArray(name) ? name : name.split('/').filter(Boolean);\n    if (parts.join('/').includes('/job/')) {\n      return trimLeadingSlash(Array.isArray(name) ? parts.join('/') : name);\n    }\n\n    return parts\n      .map(encodeURIComponent)\n      .map(s => `job/${s}`)\n      .join('/');\n  }\n}\n"],"names":["ensureTrailingSlash","createJobApi","createBuildApi","joinUrl","trimLeadingSlash","addQueryParams","safeExtractText","fetch"],"mappings":";;;;;;;;;;;AAqCO,MAAM,OAAQ,CAAA;AAAA,EACX,SAAA;AAAA,EACQ,IAAA;AAAA,EAEhB,YAAY,IAA4B,EAAA;AACtC,IAAI,IAAA,CAAC,KAAK,OAAS,EAAA;AACjB,MAAM,MAAA,IAAI,MAAM,mCAAmC,CAAA;AAAA;AAIrD,IAAI,IAAA,IAAA,CAAK,gBAAgB,KAAW,CAAA,EAAA;AAClC,MAAA,IAAA,CAAK,WAAc,GAAA,IAAA;AAAA;AAKrB,IAAM,MAAA,OAAA,GAAUA,yBAAoB,CAAA,IAAA,CAAK,OAAO,CAAA;AAChD,IAAA,IAAA,CAAK,UAAU,EAAE,OAAA,EAAS,GAAI,IAAK,CAAA,OAAA,IAAW,EAAI,EAAA;AAElD,IAAA,IAAA,CAAK,IAAO,GAAA,IAAA;AAAA;AACd;AAAA,EAGA,MAAMC,mBAAa,CAAA;AAAA,IACjB,gBAAkB,EAAA,CAAA,IAAA,KAAQ,IAAK,CAAA,gBAAA,CAAiB,IAAI,CAAA;AAAA,IACpD,SAAS,CAAC,IAAA,EAAM,SAAS,IAAK,CAAA,OAAA,CAAQ,MAAM,IAAI;AAAA,GACjD,CAAA;AAAA,EAED,QAAQC,uBAAe,CAAA;AAAA,IACrB,gBAAkB,EAAA,CAAA,IAAA,KAAQ,IAAK,CAAA,gBAAA,CAAiB,IAAI,CAAA;AAAA,IACpD,SAAS,CAAC,IAAA,EAAM,SAAS,IAAK,CAAA,OAAA,CAAQ,MAAM,IAAI;AAAA,GACjD,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBD,MAAc,QAA2C,GAAA;AACvD,IAAM,MAAA,EAAE,WAAY,EAAA,GAAI,IAAK,CAAA,IAAA;AAE7B,IAAA,IAAI,CAAC,WAAa,EAAA;AAChB,MAAO,OAAA,KAAA,CAAA;AAAA;AAGT,IAAA,IAAI,KAAK,SAAW,EAAA;AAClB,MAAA,OAAO,IAAK,CAAA,SAAA;AAAA;AAGd,IAAI,IAAA,OAAO,gBAAgB,UAAY,EAAA;AACrC,MAAK,IAAA,CAAA,SAAA,GAAY,MAAM,WAAA,CAAY,IAAI,CAAA;AACvC,MAAA,OAAO,IAAK,CAAA,SAAA;AAAA;AAId,IAAM,MAAA,GAAA,GAAM,MAAM,IAAK,CAAA,QAAA;AAAA,MACrB,CAAG,EAAAF,yBAAA,CAAoB,IAAK,CAAA,IAAA,CAAK,OAAO,CAAC,CAAA,oBAAA;AAAA,KAC3C;AACA,IAAI,IAAA,CAAC,IAAI,EAAI,EAAA;AACX,MAAO,OAAA,KAAA,CAAA;AAAA;AAET,IAAM,MAAA,IAAA,GAAQ,MAAM,GAAA,CAAI,IAAK,EAAA;AAC7B,IAAA,IAAA,CAAK,SAAY,GAAA;AAAA,MACf,YAAY,IAAK,CAAA,iBAAA;AAAA,MACjB,aAAa,IAAK,CAAA;AAAA,KACpB;AAEA,IAAA,OAAO,IAAK,CAAA,SAAA;AAAA;AACd,EAEA,MAAc,OAAA,CACZ,IACA,EAAA,IAAA,GAMI,EACU,EAAA;AACd,IAAA,IAAI,MAAM,IAAI,GAAA;AAAA,MACZG,aAAA,CAAQH,0BAAoB,IAAK,CAAA,IAAA,CAAK,OAAO,CAAG,EAAAI,sBAAA,CAAiB,IAAI,CAAC;AAAA,KACxE;AACA,IAAA,IAAI,KAAK,KAAO,EAAA;AACd,MAAM,GAAA,GAAAC,oBAAA,CAAe,GAAK,EAAA,IAAA,CAAK,KAAK,CAAA;AAAA;AAGtC,IAAM,MAAA,MAAA,GAAA,CACJ,MAAM,MAAW,KAAA,IAAA,EAAM,OAAO,MAAS,GAAA,KAAA,CAAA,EACvC,kBAAkB,OAAO,CAAA;AAC3B,IAAA,MAAM,OAAuC,GAAA;AAAA,MAC3C,GAAI,IAAA,CAAK,IAAK,CAAA,OAAA,IAAW;AAAC,KAC5B;AAGA,IAAI,IAAA,MAAA,KAAW,KAAS,IAAA,MAAA,KAAW,MAAQ,EAAA;AACzC,MAAM,MAAA,KAAA,GAAQ,MAAM,IAAA,CAAK,QAAS,EAAA;AAClC,MAAA,IAAI,KAAO,EAAA;AACT,QAAQ,OAAA,CAAA,KAAA,CAAM,UAAU,CAAA,GAAI,KAAM,CAAA,WAAA;AAGlC,QAAI,IAAA,KAAA,CAAM,SAAS,MAAQ,EAAA;AACzB,UAAA,MAAM,QACJ,OAAO,OAAA,CAAQ,MAAW,KAAA,QAAA,GAAW,QAAQ,MAAS,GAAA,EAAA;AACxD,UAAA,MAAM,KAAQ,GAAA,KAAA,CAAM,OAAQ,CAAA,IAAA,CAAK,IAAI,CAAA;AACrC,UAAA,OAAA,CAAQ,SAAS,KAAQ,GAAA,CAAA,EAAG,KAAK,CAAA,EAAA,EAAK,KAAK,CAAK,CAAA,GAAA,KAAA;AAAA;AAClD;AACF;AAKF,IAAI,IAAA,mBAAA;AACJ,IAAA,IAAI,MAAM,WAAa,EAAA;AACrB,MAAA,mBAAA,GAAsB,IAAM,EAAA,WAAA;AAAA;AAI9B,IAAA,IAAI,CAAC,mBAAA,IAAuB,IAAM,EAAA,IAAA,YAAgB,eAAiB,EAAA;AACjE,MAAsB,mBAAA,GAAA,kDAAA;AAAA;AAGxB,IAAA,IAAI,mBAAqB,EAAA;AACvB,MAAA,OAAA,CAAQ,cAAc,CAAI,GAAA,mBAAA;AAAA;AAG5B,IAAA,MAAM,MAAM,MAAM,IAAA,CAAK,QAAS,CAAA,GAAA,CAAI,UAAY,EAAA;AAAA,MAC9C,MAAA;AAAA,MACA,OAAA;AAAA,MACA,MAAM,IAAM,EAAA;AAAA,KACb,CAAA;AAED,IAAI,IAAA,CAAC,IAAI,EAAI,EAAA;AACX,MAAM,MAAA,IAAA,GAAO,MAAMC,qBAAA,CAAgB,GAAG,CAAA;AACtC,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,kBAAA,EAAqB,GAAI,CAAA,MAAM,CAAI,CAAA,EAAA,MAAM,IAAI,GAAI,CAAA,QAAA,EAAU,CAAA,EAAA,EAAK,IAAI,CAAA;AAAA,OACtE;AAAA;AAGF,IAAA,IAAI,MAAM,OAAS,EAAA;AACjB,MAAA,OAAO,IAAI,IAAK,EAAA;AAAA;AAGlB,IAAM,MAAA,WAAA,GAAA,CACJ,IAAI,OAAQ,CAAA,GAAA,CAAI,cAAc,CAAK,IAAA,EAAA,EACnC,kBAAkB,OAAO,CAAA;AAC3B,IAAI,IAAA,WAAA,CAAY,QAAS,CAAA,kBAAkB,CAAG,EAAA;AAC5C,MAAA,OAAO,IAAI,IAAK,EAAA;AAAA;AAGlB,IAAA,OAAO,IAAI,IAAK,EAAA;AAAA;AAClB,EAEA,MAAc,QACZ,CAAA,KAAA,EACA,IAKA,EAAA;AAEA,IAAA,MAAM,YAAoC,EAAC;AAC3C,IAAW,KAAA,MAAA,CAAC,CAAG,EAAA,CAAC,CAAK,IAAA,MAAA,CAAO,QAAQ,IAAM,EAAA,OAAA,IAAW,EAAE,CAAG,EAAA;AACxD,MAAI,IAAA,KAAA,CAAM,OAAQ,CAAA,CAAC,CAAG,EAAA;AACpB,QAAA,SAAA,CAAU,CAAC,CAAA,GAAI,CAAE,CAAA,IAAA,CAAK,IAAI,CAAA;AAAA,OAC5B,MAAA,IAAW,MAAM,KAAW,CAAA,EAAA;AAC1B,QAAA;AAAA,OACK,MAAA;AACL,QAAA,SAAA,CAAU,CAAC,CAAI,GAAA,CAAA;AAAA;AACjB;AAGF,IAAA,OAAOC,uBAAM,KAAO,EAAA;AAAA,MAClB,GAAI,QAAQ,EAAC;AAAA,MACb,OAAS,EAAA;AAAA,KACV,CAAA;AAAA;AACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAqBQ,iBACN,IACoB,EAAA;AACpB,IAAA,IAAI,CAAC,IAAM,EAAA;AACT,MAAM,MAAA,IAAI,MAAM,8CAA8C,CAAA;AAAA;AAGhE,IAAM,MAAA,KAAA,GAAQ,KAAM,CAAA,OAAA,CAAQ,IAAI,CAAA,GAAI,IAAO,GAAA,IAAA,CAAK,KAAM,CAAA,GAAG,CAAE,CAAA,MAAA,CAAO,OAAO,CAAA;AACzE,IAAA,IAAI,MAAM,IAAK,CAAA,GAAG,CAAE,CAAA,QAAA,CAAS,OAAO,CAAG,EAAA;AACrC,MAAO,OAAAH,sBAAA,CAAiB,MAAM,OAAQ,CAAA,IAAI,IAAI,KAAM,CAAA,IAAA,CAAK,GAAG,CAAA,GAAI,IAAI,CAAA;AAAA;AAGtE,IAAO,OAAA,KAAA,CACJ,GAAI,CAAA,kBAAkB,CACtB,CAAA,GAAA,CAAI,CAAK,CAAA,KAAA,CAAA,IAAA,EAAO,CAAC,CAAA,CAAE,CACnB,CAAA,IAAA,CAAK,GAAG,CAAA;AAAA;AAEf;;;;"}

package/dist/client.esm.js

@@ -0,0 +1,174 @@
+import fetch from 'node-fetch';
+import { createJobApi } from './client/jobApi.esm.js';
+import { createBuildApi } from './client/buildApi.esm.js';
+import { ensureTrailingSlash, joinUrl, trimLeadingSlash, addQueryParams, safeExtractText } from './client/utils.esm.js';
+
+class Jenkins {
+  crumbData;
+  opts;
+  constructor(opts) {
+    if (!opts.baseUrl) {
+      throw new Error("Jenkins: opts.baseUrl is required");
+    }
+    if (opts.crumbIssuer === void 0) {
+      opts.crumbIssuer = true;
+    }
+    const referer = ensureTrailingSlash(opts.baseUrl);
+    opts.headers = { referer, ...opts.headers ?? {} };
+    this.opts = opts;
+  }
+  // Add APIs
+  job = createJobApi({
+    normalizeJobName: (name) => this.normalizeJobName(name),
+    request: (path, opts) => this.request(path, opts)
+  });
+  build = createBuildApi({
+    normalizeJobName: (name) => this.normalizeJobName(name),
+    request: (path, opts) => this.request(path, opts)
+  });
+  /**
+   * Retrieves and caches the Jenkins CSRF protection crumb.
+   *
+   * Jenkins uses a "crumb" (similar to a CSRF token) to protect write operations
+   * such as POST requests. This method handles retrieving that crumb based on
+   * the client's configuration.
+   *
+   * Behavior:
+   * - If `crumbIssuer` is not enabled in the client options, it returns `undefined`.
+   * - If a cached crumb already exists, it is returned immediately.
+   * - If `crumbIssuer` is a function, that function is called to obtain the crumb.
+   * - Otherwise, it performs a network request to
+   *   `<baseUrl>/crumbIssuer/api/json` to fetch the crumb from Jenkins.
+   *
+   * The result is cached in `this.crumbData` for subsequent calls.
+   *
+   * @returns A `CrumbData` object containing the header name and value,
+   *          or `undefined` if no crumb issuer is configured or the request fails.
+   * @throws Any network or parsing errors that occur during the crumb fetch.
+   */
+  async getCrumb() {
+    const { crumbIssuer } = this.opts;
+    if (!crumbIssuer) {
+      return void 0;
+    }
+    if (this.crumbData) {
+      return this.crumbData;
+    }
+    if (typeof crumbIssuer === "function") {
+      this.crumbData = await crumbIssuer(this);
+      return this.crumbData;
+    }
+    const res = await this.fetchRaw(
+      `${ensureTrailingSlash(this.opts.baseUrl)}crumbIssuer/api/json`
+    );
+    if (!res.ok) {
+      return void 0;
+    }
+    const data = await res.json();
+    this.crumbData = {
+      headerName: data.crumbRequestField,
+      headerValue: data.crumb
+    };
+    return this.crumbData;
+  }
+  async request(path, opts = {}) {
+    let url = new URL(
+      joinUrl(ensureTrailingSlash(this.opts.baseUrl), trimLeadingSlash(path))
+    );
+    if (opts.query) {
+      url = addQueryParams(url, opts.query);
+    }
+    const method = (opts?.method || (opts?.body ? "POST" : "GET")).toLocaleUpperCase("en-US");
+    const headers = {
+      ...this.opts.headers ?? {}
+    };
+    if (method !== "GET" && method !== "HEAD") {
+      const crumb = await this.getCrumb();
+      if (crumb) {
+        headers[crumb.headerName] = crumb.headerValue;
+        if (crumb.cookies?.length) {
+          const prior = typeof headers.cookie === "string" ? headers.cookie : "";
+          const extra = crumb.cookies.join("; ");
+          headers.cookie = prior ? `${prior}; ${extra}` : extra;
+        }
+      }
+    }
+    let resolvedContentType;
+    if (opts?.contentType) {
+      resolvedContentType = opts?.contentType;
+    }
+    if (!resolvedContentType && opts?.body instanceof URLSearchParams) {
+      resolvedContentType = "application/x-www-form-urlencoded; charset=UTF-8";
+    }
+    if (resolvedContentType) {
+      headers["content-type"] = resolvedContentType;
+    }
+    const res = await this.fetchRaw(url.toString(), {
+      method,
+      headers,
+      body: opts?.body
+    });
+    if (!res.ok) {
+      const text = await safeExtractText(res);
+      throw new Error(
+        `Jenkins API error ${res.status} ${method} ${url.toString()}: ${text}`
+      );
+    }
+    if (opts?.rawText) {
+      return res.text();
+    }
+    const contentType = (res.headers.get("content-type") || "").toLocaleLowerCase("en-US");
+    if (contentType.includes("application/json")) {
+      return res.json();
+    }
+    return res.text();
+  }
+  async fetchRaw(input, init) {
+    const flattened = {};
+    for (const [k, v] of Object.entries(init?.headers ?? {})) {
+      if (Array.isArray(v)) {
+        flattened[k] = v.join(", ");
+      } else if (v === void 0) {
+        continue;
+      } else {
+        flattened[k] = v;
+      }
+    }
+    return fetch(input, {
+      ...init ?? {},
+      headers: flattened
+    });
+  }
+  /**
+   * Normalizes a Jenkins job name into a fully qualified job path.
+   *
+   * Jenkins job URLs use a hierarchical format like:
+   *   `/job/folder/job/subfolder/job/pipeline`
+   *
+   * This method takes a job name (either a string like `"folder/pipeline"`
+   * or an array like `["folder", "pipeline"]`) and converts it into the proper
+   * Jenkins API path format by inserting `job/` segments and URL-encoding
+   * each component.
+   *
+   * - If the input already contains `/job/` segments, it is returned as-is
+   *   (after trimming any leading slash).
+   * - If the input is undefined, an error is thrown.
+   *
+   * @param name - The job name to normalize, either as a string or an array of path segments.
+   * @returns The normalized Jenkins job path (e.g. `"job/folder/job/pipeline"`).
+   * @throws If the name is undefined or empty.
+   */
+  normalizeJobName(name) {
+    if (!name) {
+      throw new Error('Jenkins.normalizeJobName: "name" is required');
+    }
+    const parts = Array.isArray(name) ? name : name.split("/").filter(Boolean);
+    if (parts.join("/").includes("/job/")) {
+      return trimLeadingSlash(Array.isArray(name) ? parts.join("/") : name);
+    }
+    return parts.map(encodeURIComponent).map((s) => `job/${s}`).join("/");
+  }
+}
+
+export { Jenkins };
+//# sourceMappingURL=client.esm.js.map

package/dist/client.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.esm.js","sources":["../src/client.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport fetch from 'node-fetch';\nimport { createJobApi } from './client/jobApi';\nimport { createBuildApi } from './client/buildApi';\nimport { CrumbData, CrumbDataHeaderValues, HeaderValue } from './client/types';\n\nimport {\n  addQueryParams,\n  joinUrl,\n  trimLeadingSlash,\n  ensureTrailingSlash,\n  safeExtractText,\n} from './client/utils';\n\n/** @public */\nexport interface JenkinsClientOptions {\n  baseUrl: string; // e.g. \"https://jenkins.example.com\"\n  crumbIssuer?: boolean | ((client: any) => Promise<CrumbData>) | undefined;\n  headers?: Record<string, HeaderValue>;\n  promisify?: boolean; // For compatibility with old legacy API, not used.\n}\n\n/** @public */\nexport class Jenkins {\n  private crumbData?: CrumbData;\n  public readonly opts: JenkinsClientOptions;\n\n  constructor(opts: JenkinsClientOptions) {\n    if (!opts.baseUrl) {\n      throw new Error('Jenkins: opts.baseUrl is required');\n    }\n\n    // Legacy client behavior: set crumbIssuer to true if unset.\n    if (opts.crumbIssuer === undefined) {\n      opts.crumbIssuer = true;\n    }\n\n    // Legacy client behavior: set default headers and Referer\n    // The referer here is the baseUrl.\n    const referer = ensureTrailingSlash(opts.baseUrl);\n    opts.headers = { referer, ...(opts.headers ?? {}) };\n\n    this.opts = opts;\n  }\n\n  // Add APIs\n  job = createJobApi({\n    normalizeJobName: name => this.normalizeJobName(name),\n    request: (path, opts) => this.request(path, opts),\n  });\n\n  build = createBuildApi({\n    normalizeJobName: name => this.normalizeJobName(name),\n    request: (path, opts) => this.request(path, opts),\n  });\n\n  /**\n   * Retrieves and caches the Jenkins CSRF protection crumb.\n   *\n   * Jenkins uses a \"crumb\" (similar to a CSRF token) to protect write operations\n   * such as POST requests. This method handles retrieving that crumb based on\n   * the client's configuration.\n   *\n   * Behavior:\n   * - If `crumbIssuer` is not enabled in the client options, it returns `undefined`.\n   * - If a cached crumb already exists, it is returned immediately.\n   * - If `crumbIssuer` is a function, that function is called to obtain the crumb.\n   * - Otherwise, it performs a network request to\n   *   `<baseUrl>/crumbIssuer/api/json` to fetch the crumb from Jenkins.\n   *\n   * The result is cached in `this.crumbData` for subsequent calls.\n   *\n   * @returns A `CrumbData` object containing the header name and value,\n   *          or `undefined` if no crumb issuer is configured or the request fails.\n   * @throws Any network or parsing errors that occur during the crumb fetch.\n   */\n  private async getCrumb(): Promise<CrumbData | undefined> {\n    const { crumbIssuer } = this.opts;\n\n    if (!crumbIssuer) {\n      return undefined;\n    }\n\n    if (this.crumbData) {\n      return this.crumbData;\n    }\n\n    if (typeof crumbIssuer === 'function') {\n      this.crumbData = await crumbIssuer(this);\n      return this.crumbData;\n    }\n\n    // Fetch crumb from Jenkins\n    const res = await this.fetchRaw(\n      `${ensureTrailingSlash(this.opts.baseUrl)}crumbIssuer/api/json`,\n    );\n    if (!res.ok) {\n      return undefined;\n    }\n    const data = (await res.json()) as CrumbDataHeaderValues;\n    this.crumbData = {\n      headerName: data.crumbRequestField,\n      headerValue: data.crumb,\n    };\n\n    return this.crumbData;\n  }\n\n  private async request(\n    path: string,\n    opts: {\n      method?: string;\n      query?: Record<string, string | number | undefined>;\n      body?: any;\n      rawText?: boolean;\n      contentType?: string;\n    } = {},\n  ): Promise<any> {\n    let url = new URL(\n      joinUrl(ensureTrailingSlash(this.opts.baseUrl), trimLeadingSlash(path)),\n    );\n    if (opts.query) {\n      url = addQueryParams(url, opts.query);\n    }\n\n    const method = (\n      opts?.method || (opts?.body ? 'POST' : 'GET')\n    ).toLocaleUpperCase('en-US');\n    const headers: Record<string, HeaderValue> = {\n      ...(this.opts.headers ?? {}),\n    };\n\n    // Legacy client support: Add crumb if request is not read-only\n    if (method !== 'GET' && method !== 'HEAD') {\n      const crumb = await this.getCrumb();\n      if (crumb) {\n        headers[crumb.headerName] = crumb.headerValue;\n        // If the crumb call told us to include some cookies, merge them into\n        // the existing cookie header\n        if (crumb.cookies?.length) {\n          const prior =\n            typeof headers.cookie === 'string' ? headers.cookie : '';\n          const extra = crumb.cookies.join('; ');\n          headers.cookie = prior ? `${prior}; ${extra}` : extra;\n        }\n      }\n    }\n\n    // Set Content-Type, default to undefined if not set\n    // Check caller-specified content-type first\n    let resolvedContentType: string | undefined;\n    if (opts?.contentType) {\n      resolvedContentType = opts?.contentType;\n    }\n\n    // URLSearchParams -> x-www-form-urlencoded\n    if (!resolvedContentType && opts?.body instanceof URLSearchParams) {\n      resolvedContentType = 'application/x-www-form-urlencoded; charset=UTF-8';\n    }\n\n    if (resolvedContentType) {\n      headers['content-type'] = resolvedContentType;\n    }\n\n    const res = await this.fetchRaw(url.toString(), {\n      method,\n      headers,\n      body: opts?.body,\n    });\n\n    if (!res.ok) {\n      const text = await safeExtractText(res);\n      throw new Error(\n        `Jenkins API error ${res.status} ${method} ${url.toString()}: ${text}`,\n      );\n    }\n\n    if (opts?.rawText) {\n      return res.text();\n    }\n\n    const contentType = (\n      res.headers.get('content-type') || ''\n    ).toLocaleLowerCase('en-US');\n    if (contentType.includes('application/json')) {\n      return res.json();\n    }\n\n    return res.text();\n  }\n\n  private async fetchRaw(\n    input: string,\n    init?: {\n      method?: string;\n      headers?: Record<string, HeaderValue>;\n      body?: any;\n    },\n  ) {\n    // Flatten the values passed in \"headers\"\n    const flattened: Record<string, string> = {};\n    for (const [k, v] of Object.entries(init?.headers ?? {})) {\n      if (Array.isArray(v)) {\n        flattened[k] = v.join(', ');\n      } else if (v === undefined) {\n        continue;\n      } else {\n        flattened[k] = v;\n      }\n    }\n\n    return fetch(input, {\n      ...(init ?? {}),\n      headers: flattened as any,\n    });\n  }\n\n  /**\n   * Normalizes a Jenkins job name into a fully qualified job path.\n   *\n   * Jenkins job URLs use a hierarchical format like:\n   *   `/job/folder/job/subfolder/job/pipeline`\n   *\n   * This method takes a job name (either a string like `\"folder/pipeline\"`\n   * or an array like `[\"folder\", \"pipeline\"]`) and converts it into the proper\n   * Jenkins API path format by inserting `job/` segments and URL-encoding\n   * each component.\n   *\n   * - If the input already contains `/job/` segments, it is returned as-is\n   *   (after trimming any leading slash).\n   * - If the input is undefined, an error is thrown.\n   *\n   * @param name - The job name to normalize, either as a string or an array of path segments.\n   * @returns The normalized Jenkins job path (e.g. `\"job/folder/job/pipeline\"`).\n   * @throws If the name is undefined or empty.\n   */\n  private normalizeJobName(\n    name: string | string[] | undefined,\n  ): string | undefined {\n    if (!name) {\n      throw new Error('Jenkins.normalizeJobName: \"name\" is required');\n    }\n\n    const parts = Array.isArray(name) ? name : name.split('/').filter(Boolean);\n    if (parts.join('/').includes('/job/')) {\n      return trimLeadingSlash(Array.isArray(name) ? parts.join('/') : name);\n    }\n\n    return parts\n      .map(encodeURIComponent)\n      .map(s => `job/${s}`)\n      .join('/');\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/index.cjs.js

@@ -1,9 +1,11 @@
 'use strict';
 
 var permissions = require('./permissions.cjs.js');
+var client = require('./client.cjs.js');
 
 
 
 exports.jenkinsExecutePermission = permissions.jenkinsExecutePermission;
 exports.jenkinsPermissions = permissions.jenkinsPermissions;
+exports.Jenkins = client.Jenkins;
 //# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;"}
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}

package/dist/index.d.ts

@@ -13,4 +13,119 @@ declare const jenkinsExecutePermission: _backstage_plugin_permission_common.Reso
  */
 declare const jenkinsPermissions: _backstage_plugin_permission_common.ResourcePermission<"catalog-entity">[];
 
-export { jenkinsExecutePermission, jenkinsPermissions };
+/** @public */
+interface CommonBuild {
+    timestamp: number;
+    building: boolean;
+    duration: number;
+    result?: string;
+    fullDisplayName: string;
+    displayName: string;
+    url: string;
+    number: number;
+}
+/** @public */
+interface JenkinsBuild extends CommonBuild {
+    actions: any;
+}
+
+/** @public */
+interface CrumbData {
+    headerName: string;
+    headerValue: string;
+    cookies?: string[];
+}
+/** @public */
+interface CrumbDataHeaderValues {
+    crumbRequestField: string;
+    crumb: string;
+}
+/** @public */
+type HeaderValue = string | string[] | undefined;
+/** @public */
+type JenkinsParams = Record<string, unknown> | URLSearchParams | undefined;
+/** @public */
+interface JobBuildOptions {
+    parameters?: JenkinsParams;
+    token?: string;
+    delay?: string;
+}
+/** @public */
+interface JobGetOptions {
+    name: string | string[];
+    tree?: string;
+    depth?: number;
+}
+
+/** @public */
+interface JenkinsClientOptions {
+    baseUrl: string;
+    crumbIssuer?: boolean | ((client: any) => Promise<CrumbData>) | undefined;
+    headers?: Record<string, HeaderValue>;
+    promisify?: boolean;
+}
+/** @public */
+declare class Jenkins {
+    private crumbData?;
+    readonly opts: JenkinsClientOptions;
+    constructor(opts: JenkinsClientOptions);
+    job: {
+        get: (input: JobGetOptions) => Promise<any>;
+        getBuilds: (name: string | string[], tree?: string) => Promise<unknown>;
+        build: (name: string | string[], opts?: JobBuildOptions | undefined) => Promise<unknown>;
+        copy: (name: string | string[], from: string) => Promise<void>;
+        create: (name: string | string[], xml: string) => Promise<void>;
+        destroy: (name: string | string[]) => Promise<void>;
+        enable: (name: string | string[]) => Promise<void>;
+        disable: (name: string | string[]) => Promise<void>;
+    };
+    build: {
+        get: (name: string | string[], buildNumber: string | number) => Promise<JenkinsBuild>;
+        getConsoleText: (name: string | string[], buildNumber: string | number) => Promise<string>;
+    };
+    /**
+     * Retrieves and caches the Jenkins CSRF protection crumb.
+     *
+     * Jenkins uses a "crumb" (similar to a CSRF token) to protect write operations
+     * such as POST requests. This method handles retrieving that crumb based on
+     * the client's configuration.
+     *
+     * Behavior:
+     * - If `crumbIssuer` is not enabled in the client options, it returns `undefined`.
+     * - If a cached crumb already exists, it is returned immediately.
+     * - If `crumbIssuer` is a function, that function is called to obtain the crumb.
+     * - Otherwise, it performs a network request to
+     *   `<baseUrl>/crumbIssuer/api/json` to fetch the crumb from Jenkins.
+     *
+     * The result is cached in `this.crumbData` for subsequent calls.
+     *
+     * @returns A `CrumbData` object containing the header name and value,
+     *          or `undefined` if no crumb issuer is configured or the request fails.
+     * @throws Any network or parsing errors that occur during the crumb fetch.
+     */
+    private getCrumb;
+    private request;
+    private fetchRaw;
+    /**
+     * Normalizes a Jenkins job name into a fully qualified job path.
+     *
+     * Jenkins job URLs use a hierarchical format like:
+     *   `/job/folder/job/subfolder/job/pipeline`
+     *
+     * This method takes a job name (either a string like `"folder/pipeline"`
+     * or an array like `["folder", "pipeline"]`) and converts it into the proper
+     * Jenkins API path format by inserting `job/` segments and URL-encoding
+     * each component.
+     *
+     * - If the input already contains `/job/` segments, it is returned as-is
+     *   (after trimming any leading slash).
+     * - If the input is undefined, an error is thrown.
+     *
+     * @param name - The job name to normalize, either as a string or an array of path segments.
+     * @returns The normalized Jenkins job path (e.g. `"job/folder/job/pipeline"`).
+     * @throws If the name is undefined or empty.
+     */
+    private normalizeJobName;
+}
+
+export { type CommonBuild, type CrumbData, type CrumbDataHeaderValues, type HeaderValue, Jenkins, type JenkinsBuild, type JenkinsClientOptions, type JenkinsParams, type JobBuildOptions, type JobGetOptions, jenkinsExecutePermission, jenkinsPermissions };

package/dist/index.esm.js

@@ -1,2 +1,3 @@
 export { jenkinsExecutePermission, jenkinsPermissions } from './permissions.esm.js';
+export { Jenkins } from './client.esm.js';
 //# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage-community/plugin-jenkins-common",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "backstage": {
     "role": "common-library",
     "pluginId": "jenkins",
@@ -38,11 +38,13 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/plugin-catalog-common": "^1.1.6",
-    "@backstage/plugin-permission-common": "^0.9.2"
+    "@backstage/plugin-catalog-common": "^1.1.7",
+    "@backstage/plugin-permission-common": "^0.9.3",
+    "form-data": "^4.0.4",
+    "node-fetch": "^2.6.7"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.34.4"
+    "@backstage/cli": "^0.34.5"
   },
   "typesVersions": {
     "*": {