@trustify-da/trustify-da-javascript-client 0.3.0-ea.608d6fa → 0.3.0-ea.62b88e5

package/dist/src/analysis.d.ts

@@ -1,8 +1,12 @@
+/** Media type for CycloneDX JSON batch payloads (batch-analysis API). */
+export const CYCLONEDX_JSON_MEDIA_TYPE: "application/vnd.cyclonedx+json";
 declare namespace _default {
     export { requestComponent };
     export { requestStack };
+    export { requestStackBatch };
     export { requestImages };
     export { validateToken };
+    export { appendAnalysisQueryParams };
 }
 export default _default;
 /**
@@ -11,28 +15,62 @@ export default _default;
  * @param {string} manifest - path for the manifest
  * @param {string} url - the backend url to send the request to
  * @param {import("index.js").Options} [opts={}] - optional various options to pass along the application
- * @returns {Promise<import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport').AnalysisReport>}
+ * @returns {Promise<import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>}
  */
-declare function requestComponent(provider: import("./provider").Provider, manifest: string, url: string, opts?: import("index.js").Options): Promise<import("@trustify-da/trustify-da-api-model/model/v5/AnalysisReport").AnalysisReport>;
+declare function requestComponent(provider: any, manifest: string, url: string, opts?: any): Promise<import("@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts").AnalysisReport>;
 /**
- * Send a stack analysis request and get the report as 'text/html' or 'application/json'.
- * @param {import('./provider').Provider} provider - the provided data for constructing the request
- * @param {string} manifest - path for the manifest
- * @param {string} url - the backend url to send the request to
- * @param {boolean} [html=false] - true will return 'text/html', false will return 'application/json'
- * @param {import("index.js").Options} [opts={}] - optional various options to pass along the application
- * @returns {Promise<string|import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport').AnalysisReport>}
+ * @overload
+ * @param {import('./provider').Provider} provider
+ * @param {string} manifest
+ * @param {string} url
+ * @param {true} [html]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<string>}
  */
-declare function requestStack(provider: import("./provider").Provider, manifest: string, url: string, html?: boolean, opts?: import("index.js").Options): Promise<string | import("@trustify-da/trustify-da-api-model/model/v5/AnalysisReport").AnalysisReport>;
+declare function requestStack(provider: any, manifest: string, url: string, html?: true | undefined, opts?: any): Promise<string>;
+/**
+ * @overload
+ * @param {import('./provider').Provider} provider
+ * @param {string} manifest
+ * @param {string} url
+ * @param {false} [html]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>>}
+ */
+declare function requestStack(provider: any, manifest: string, url: string, html?: false | undefined, opts?: any): Promise<import("@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts").AnalysisReport>;
+/**
+ * @overload
+ * @param {Object.<string, object>} sbomByPurl
+ * @param {string} url
+ * @param {true} [html=false]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<string>}
+ */
+declare function requestStackBatch(sbomByPurl: {
+    [x: string]: object;
+}, url: string, html?: true | undefined, opts?: any): Promise<string>;
+/**
+ * @overload
+ * @param {Object.<string, object>} sbomByPurl
+ * @param {string} url
+ * @param {false} [html=false]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>>}
+ */
+declare function requestStackBatch(sbomByPurl: {
+    [x: string]: object;
+}, url: string, html?: false | undefined, opts?: any): Promise<{
+    [x: string]: import("@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts").AnalysisReport;
+}>;
 /**
  *
  * @param {Array<string>} imageRefs
  * @param {string} url
  * @param {import("index.js").Options} [opts={}] - optional various options to pass along the application
- * @returns {Promise<string|Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport').AnalysisReport>>}
+ * @returns {Promise<string|Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>>}
  */
-declare function requestImages(imageRefs: Array<string>, url: string, html?: boolean, opts?: import("index.js").Options): Promise<string | {
-    [x: string]: import("@trustify-da/trustify-da-api-model/model/v5/AnalysisReport").AnalysisReport;
+declare function requestImages(imageRefs: Array<string>, url: string, html?: boolean, opts?: any): Promise<string | {
+    [x: string]: import("@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts").AnalysisReport;
 }>;
 /**
  *
@@ -40,4 +78,10 @@ declare function requestImages(imageRefs: Array<string>, url: string, html?: boo
  * @param {import("index.js").Options} [opts={}] - optional various options to pass headers for t he validateToken Request
  * @return {Promise<number>} return the HTTP status Code of the response from the validate token request.
  */
-declare function validateToken(url: any, opts?: import("index.js").Options): Promise<number>;
+declare function validateToken(url: any, opts?: any): Promise<number>;
+/**
+ * Append common analysis query parameters (recommend, providers, sources) to a URL.
+ * @param {URL} url - the URL object to append query parameters to
+ * @param {import("index.js").Options} [opts={}] - options containing parameter overrides
+ */
+declare function appendAnalysisQueryParams(url: URL, opts?: any): void;

package/dist/src/analysis.js

@@ -4,7 +4,27 @@ import { EOL } from "os";
 import { runLicenseCheck } from "./license/index.js";
 import { generateImageSBOM, parseImageRef } from "./oci_image/utils.js";
 import { addProxyAgent, getCustom, getTokenHeaders, TRUSTIFY_DA_OPERATION_TYPE_HEADER, TRUSTIFY_DA_PACKAGE_MANAGER_HEADER } from "./tools.js";
-export default { requestComponent, requestStack, requestImages, validateToken };
+/** Media type for CycloneDX JSON batch payloads (batch-analysis API). */
+export const CYCLONEDX_JSON_MEDIA_TYPE = 'application/vnd.cyclonedx+json';
+export default { requestComponent, requestStack, requestStackBatch, requestImages, validateToken, appendAnalysisQueryParams };
+/**
+ * @overload
+ * @param {import('./provider').Provider} provider
+ * @param {string} manifest
+ * @param {string} url
+ * @param {true} [html]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<string>}
+ */
+/**
+ * @overload
+ * @param {import('./provider').Provider} provider
+ * @param {string} manifest
+ * @param {string} url
+ * @param {false} [html]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>>}
+ */
 /**
  * Send a stack analysis request and get the report as 'text/html' or 'application/json'.
  * @param {import('./provider').Provider} provider - the provided data for constructing the request
@@ -12,12 +32,15 @@ export default { requestComponent, requestStack, requestImages, validateToken };
  * @param {string} url - the backend url to send the request to
  * @param {boolean} [html=false] - true will return 'text/html', false will return 'application/json'
  * @param {import("index.js").Options} [opts={}] - optional various options to pass along the application
- * @returns {Promise<string|import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport').AnalysisReport>}
+ * @returns {Promise<string|import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>}
  */
 async function requestStack(provider, manifest, url, html = false, opts = {}) {
     opts["source-manifest"] = Buffer.from(fs.readFileSync(manifest).toString()).toString('base64');
     opts["manifest-type"] = path.parse(manifest).base;
     let provided = await provider.provideStack(manifest, opts); // throws error if content providing failed
+    if (provided.batch) {
+        return requestStackBatch(JSON.parse(provided.content), url, html, opts);
+    }
     opts["source-manifest"] = "";
     opts[TRUSTIFY_DA_OPERATION_TYPE_HEADER.toUpperCase().replaceAll("-", "_")] = "stack-analysis";
     let startTime = new Date();
@@ -36,9 +59,7 @@ async function requestStack(provider, manifest, url, html = false, opts = {}) {
         body: provided.content
     }, opts);
     const finalUrl = new URL(`${url}/api/v5/analysis`);
-    if (opts['TRUSTIFY_DA_RECOMMENDATIONS_ENABLED'] === 'false') {
-        finalUrl.searchParams.append('recommend', 'false');
-    }
+    appendAnalysisQueryParams(finalUrl, opts);
     let resp = await fetch(finalUrl, fetchOptions);
     let result;
     if (resp.status === 200) {
@@ -72,11 +93,14 @@ async function requestStack(provider, manifest, url, html = false, opts = {}) {
  * @param {string} manifest - path for the manifest
  * @param {string} url - the backend url to send the request to
  * @param {import("index.js").Options} [opts={}] - optional various options to pass along the application
- * @returns {Promise<import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport').AnalysisReport>}
+ * @returns {Promise<import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>}
  */
 async function requestComponent(provider, manifest, url, opts = {}) {
     opts["source-manifest"] = Buffer.from(fs.readFileSync(manifest).toString()).toString('base64');
     let provided = await provider.provideComponent(manifest, opts); // throws error if content providing failed
+    if (provided.batch) {
+        return requestStackBatch(JSON.parse(provided.content), url, false, opts);
+    }
     opts["source-manifest"] = "";
     opts[TRUSTIFY_DA_OPERATION_TYPE_HEADER.toUpperCase().replaceAll("-", "_")] = "component-analysis";
     if (process.env["TRUSTIFY_DA_DEBUG"] === "true") {
@@ -93,9 +117,7 @@ async function requestComponent(provider, manifest, url, opts = {}) {
         body: provided.content
     }, opts);
     const finalUrl = new URL(`${url}/api/v5/analysis`);
-    if (opts['TRUSTIFY_DA_RECOMMENDATIONS_ENABLED'] === 'false') {
-        finalUrl.searchParams.append('recommend', 'false');
-    }
+    appendAnalysisQueryParams(finalUrl, opts);
     let resp = await fetch(finalUrl, fetchOptions);
     let result;
     if (resp.status === 200) {
@@ -109,7 +131,9 @@ async function requestComponent(provider, manifest, url, opts = {}) {
             console.log(JSON.stringify(result, null, 4));
             console.log("Ending time of sending component analysis request to Trustify DA backend server= " + new Date());
         }
-        const licenseCheckEnabled = getCustom('TRUSTIFY_DA_LICENSE_CHECK', 'true', opts) !== 'false' && opts.licenseCheck !== false;
+        const licenseCheckEnabled = typeof opts.licenseCheck === 'boolean'
+            ? opts.licenseCheck
+            : getCustom('TRUSTIFY_DA_LICENSE_CHECK', 'true', opts) !== 'false';
         if (licenseCheckEnabled) {
             try {
                 result.licenseSummary = await runLicenseCheck(provided.content, manifest, url, opts, result);
@@ -124,12 +148,72 @@ async function requestComponent(provider, manifest, url, opts = {}) {
     }
     return Promise.resolve(result);
 }
+/**
+ * @overload
+ * @param {Object.<string, object>} sbomByPurl
+ * @param {string} url
+ * @param {true} [html=false]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<string>}
+ */
+/**
+ * @overload
+ * @param {Object.<string, object>} sbomByPurl
+ * @param {string} url
+ * @param {false} [html=false]
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>>}
+ */
+/**
+ * Send a batch stack analysis request for multiple manifests (SBOMs keyed by purl).
+ * @param {Object.<string, object>} sbomByPurl - Map of root purl to CycloneDX SBOM object
+ * @param {string} url - the backend url
+ * @param {boolean} [html=false] - true returns HTML, false returns JSON
+ * @param {import("index.js").Options} [opts={}]
+ * @returns {Promise<string|Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>>}
+ */
+async function requestStackBatch(sbomByPurl, url, html = false, opts = {}) {
+    const finalUrl = new URL(`${url}/api/v5/batch-analysis`);
+    appendAnalysisQueryParams(finalUrl, opts);
+    const fetchOptions = addProxyAgent({
+        method: 'POST',
+        headers: {
+            'Accept': html ? 'text/html' : 'application/json',
+            'Content-Type': CYCLONEDX_JSON_MEDIA_TYPE,
+            ...getTokenHeaders(opts)
+        },
+        body: JSON.stringify(sbomByPurl)
+    }, opts);
+    const resp = await fetch(finalUrl, fetchOptions);
+    if (resp.status === 200) {
+        let result;
+        if (!html) {
+            result = await resp.json();
+        }
+        else {
+            result = await resp.text();
+        }
+        if (process.env["TRUSTIFY_DA_DEBUG"] === "true") {
+            const exRequestId = resp.headers.get("ex-request-id");
+            if (exRequestId) {
+                console.log("Unique Identifier associated with this request - ex-request-id=" + exRequestId);
+            }
+            console.log("Response body received from Trustify DA backend server : " + EOL + EOL);
+            console.log(JSON.stringify(result, null, 4));
+            console.log("Ending time of sending batch stack analysis request to Trustify DA backend server= " + new Date());
+        }
+        return result;
+    }
+    else {
+        throw new Error(`Got error response from Trustify DA backend - http return code : ${resp.status}, ex-request-id: ${resp.headers.get("ex-request-id")}  error message =>  ${await resp.text()}`);
+    }
+}
 /**
  *
  * @param {Array<string>} imageRefs
  * @param {string} url
  * @param {import("index.js").Options} [opts={}] - optional various options to pass along the application
- * @returns {Promise<string|Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport').AnalysisReport>>}
+ * @returns {Promise<string|Object.<string, import('@trustify-da/trustify-da-api-model/model/v5/AnalysisReport.ts').AnalysisReport>>}
  */
 async function requestImages(imageRefs, url, html = false, opts = {}) {
     const imageSboms = {};
@@ -138,18 +222,17 @@ async function requestImages(imageRefs, url, html = false, opts = {}) {
         imageSboms[parsedImageRef.getPackageURL().toString()] = generateImageSBOM(parsedImageRef, opts);
     }
     const finalUrl = new URL(`${url}/api/v5/batch-analysis`);
-    if (opts['TRUSTIFY_DA_RECOMMENDATIONS_ENABLED'] === 'false') {
-        finalUrl.searchParams.append('recommend', 'false');
-    }
-    const resp = await fetch(finalUrl, {
+    appendAnalysisQueryParams(finalUrl, opts);
+    const fetchOptions = addProxyAgent({
         method: 'POST',
         headers: {
             'Accept': html ? 'text/html' : 'application/json',
-            'Content-Type': 'application/vnd.cyclonedx+json',
+            'Content-Type': CYCLONEDX_JSON_MEDIA_TYPE,
             ...getTokenHeaders(opts)
         },
         body: JSON.stringify(imageSboms),
-    });
+    }, opts);
+    const resp = await fetch(finalUrl, fetchOptions);
     if (resp.status === 200) {
         let result;
         if (!html) {
@@ -173,6 +256,24 @@ async function requestImages(imageRefs, url, html = false, opts = {}) {
         throw new Error(`Got error response from Trustify DA backend - http return code : ${resp.status}, ex-request-id: ${resp.headers.get("ex-request-id")}  error message =>  ${await resp.text()}`);
     }
 }
+/**
+ * Append common analysis query parameters (recommend, providers, sources) to a URL.
+ * @param {URL} url - the URL object to append query parameters to
+ * @param {import("index.js").Options} [opts={}] - options containing parameter overrides
+ */
+function appendAnalysisQueryParams(url, opts = {}) {
+    if (getCustom('TRUSTIFY_DA_RECOMMEND', 'true', opts) === 'false') {
+        url.searchParams.append('recommend', 'false');
+    }
+    const providers = getCustom('TRUSTIFY_DA_PROVIDERS', null, opts);
+    if (providers) {
+        url.searchParams.append('providers', providers);
+    }
+    const sources = getCustom('TRUSTIFY_DA_SOURCES', null, opts);
+    if (sources) {
+        url.searchParams.append('sources', sources);
+    }
+}
 /**
  *
  * @param url the backend url to send the request to

package/dist/src/batch_opts.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Whether to skip failed manifests and continue (default), or fail on first SBOM/validation error.
+ * `opts.continueOnError` overrides; env `TRUSTIFY_DA_CONTINUE_ON_ERROR=false` disables continuation.
+ *
+ * @param {{ continueOnError?: boolean, TRUSTIFY_DA_CONTINUE_ON_ERROR?: string, [key: string]: unknown }} [opts={}]
+ * @returns {boolean} true = collect errors (default), false = fail-fast
+ */
+export function resolveContinueOnError(opts?: {
+    continueOnError?: boolean;
+    TRUSTIFY_DA_CONTINUE_ON_ERROR?: string;
+    [key: string]: unknown;
+}): boolean;
+/**
+ * When true, `stackAnalysisBatch` returns `{ analysis, metadata }` instead of the backend response only.
+ * `opts.batchMetadata` overrides; env `TRUSTIFY_DA_BATCH_METADATA=true` enables.
+ *
+ * @param {{ batchMetadata?: boolean, TRUSTIFY_DA_BATCH_METADATA?: string, [key: string]: unknown }} [opts={}]
+ * @returns {boolean}
+ */
+export function resolveBatchMetadata(opts?: {
+    batchMetadata?: boolean;
+    TRUSTIFY_DA_BATCH_METADATA?: string;
+    [key: string]: unknown;
+}): boolean;

package/dist/src/batch_opts.js

@@ -0,0 +1,35 @@
+import { getCustom } from './tools.js';
+/**
+ * Whether to skip failed manifests and continue (default), or fail on first SBOM/validation error.
+ * `opts.continueOnError` overrides; env `TRUSTIFY_DA_CONTINUE_ON_ERROR=false` disables continuation.
+ *
+ * @param {{ continueOnError?: boolean, TRUSTIFY_DA_CONTINUE_ON_ERROR?: string, [key: string]: unknown }} [opts={}]
+ * @returns {boolean} true = collect errors (default), false = fail-fast
+ */
+export function resolveContinueOnError(opts = {}) {
+    if (typeof opts.continueOnError === 'boolean') {
+        return opts.continueOnError;
+    }
+    const v = getCustom('TRUSTIFY_DA_CONTINUE_ON_ERROR', null, opts);
+    if (v != null && String(v).trim() !== '') {
+        return String(v).toLowerCase() !== 'false';
+    }
+    return true;
+}
+/**
+ * When true, `stackAnalysisBatch` returns `{ analysis, metadata }` instead of the backend response only.
+ * `opts.batchMetadata` overrides; env `TRUSTIFY_DA_BATCH_METADATA=true` enables.
+ *
+ * @param {{ batchMetadata?: boolean, TRUSTIFY_DA_BATCH_METADATA?: string, [key: string]: unknown }} [opts={}]
+ * @returns {boolean}
+ */
+export function resolveBatchMetadata(opts = {}) {
+    if (typeof opts.batchMetadata === 'boolean') {
+        return opts.batchMetadata;
+    }
+    const v = getCustom('TRUSTIFY_DA_BATCH_METADATA', null, opts);
+    if (v != null && String(v).trim() !== '') {
+        return String(v).toLowerCase() === 'true';
+    }
+    return false;
+}