JFrog Javascript Client

JFrog Javascript Client is a Javascript library, which wraps some REST APIs exposed by JFrog's different services.

Contributions

We welcome pull requests from the community. To help us improve this project, please read our contribution guide.

Getting started

Add jfrog-client-js as a dependency to your package.json file:

"dependencies": {
  "jfrog-client-js": "^2.0.0"
}

APIs

• Setting up JFrog client
• Xray
  • Pinging Xray
  • Getting Xray Version
  • Checking Xray Entitlement
  • Scanning Bulk of Dependencies
  • Scanning a Dependency Tree with Consideration to the JFrog Project
  • Scanning a Dependency Tree with Consideration to the Xray Watches
  • Retrieving Xray Build Details
• Artifactory
  • Pinging Artifactory
  • Getting Artifactory Version
  • Downloading an Artifact
  • Downloading an Artifact content
  • Downloading an Artifact to file
  • Downloading an Artifact checksum
  • Searching by AQL
• Platform
  • Register For Web Login
  • Get Access Token From Web Login
• Xray Source Control
  • Getting Xsc Version
  • Sending Log Message Event
  • Sending Start Scan Event
  • Sending End Scan Event
  • Getting Scan Event Details

Setting up JFrog client

let jfrogClient = new JfrogClient({
  platformUrl: 'https://my-platform-url.jfrog.io/',
  // artifactoryUrl - Set to use a custom Artifactory URL.
  // xrayUrl - Set to use a custom Xray URL.
  username: 'username',
  password: 'password',
  // OR
  accessToken: 'accessToken',

  // Optional parameters
  proxy: { host: '<organization>-xray.jfrog.io', port: 8081, protocol: 'https' },
  headers: { key1: 'value1', key2: 'value2' },
  // Connection retries. If not defined, the default value is 5.
  retries: 5,
  // Timeout before the connection is terminated in milliseconds, the default value is 60 seconds
  timeout: 60000,
  // Status codes that trigger retries. the default is network error or a 5xx status code.
  retryOnStatusCode: (statusCode: number) => statusCode >= 500;,
  // Delay between retries, in milliseconds. The default is 1000 milliseconds.
  retryDelay: 1000,
});

Xray

Pinging Xray

jfrogClient
  .xray()
  .system()
  .ping()
  .then((result) => {
    console.log(result);
  })
  .catch((error) => {
    console.error(error);
  });

Getting Xray Version

jfrogClient
  .xray()
  .system()
  .version()
  .then((result) => {
    console.log(result);
  })
  .catch((error) => {
    console.error(error);
  });

Checking Xray Entitlement

let feature = 'contextual_analysis';
jfrogClient
  .xray()
  .entitlements()
  .feature(feature)
  .then((result) => {
    console.log(result);
  })
  .catch((error) => {
    console.error(error);
  });

Scanning Bulk of Dependencies

let express = new ComponentDetails('npm://express:4.0.0');
let request = new ComponentDetails('npm://request:2.0.0');
jfrogClient
  .xray()
  .summary()
  .component({
    component_details: [express, request],
  })
  .then((result) => {
    console.log(JSON.stringify(result));
  })
  .catch((error) => {
    console.error(error);
  });

Scanning a Dependency Tree with Consideration to the JFrog Project

const progress: XrayScanProgress = {
    setPercentage(percentage: number): void {
        // Add progress
    },
} as XrayScanProgress;

jfrogClient.xray().scan().graph({
  component_id: 'root-node',
  nodes: [{component_id: 'npm://express:4.0.0'}, {component_id: 'npm://request:2.0.0'}]
  }, progress, () => { /* if (something) throw Error('Aborted')*/ }, 'projectKey', [])
  .then(result => {
    console.log(JSON.stringify(result));
  })
  .catch(error => {
    console.error(error);
  });

Scanning a Dependency Tree with Consideration to the Xray Watches

const progress: XrayScanProgress = {
    setPercentage(percentage: number): void {
        // Add progress
    },
} as XrayScanProgress;

jfrogClient.xray().scan().graph({
  component_id: 'root-node',
  nodes: [{component_id: 'npm://express:4.0.0'}, {component_id: 'npm://request:2.0.0'}]
  }, progress, () => { /* if (something) throw Error('Aborted')*/ }, '', ['watch-1', 'watch-2'])
  .then(result => {
    console.log(JSON.stringify(result));
  })
  .catch(error => {
    console.error(error);
  });

Retrieving Xray Build Details

jfrogClient
  .xray()
  .details()
  .build('Build Name', '1', 'Optional Project Key')
  .then((result) => {
    console.log(JSON.stringify(result));
  })
  .catch((error) => {
    console.error(error);
  });

Artifactory

Pinging Artifactory

jfrogClient
  .artifactory()
  .system()
  .ping()
  .then((result) => {
    console.log(result);
  })
  .catch((error) => {
    console.error(error);
  });

Getting Artifactory Version

jfrogClient
  .artifactory()
  .system()
  .version()
  .then((result) => {
    console.log(result);
  })
  .catch((error) => {
    console.error(error);
  });

Downloading an Artifact

jfrogClient
  .artifactory()
  .download()
  .downloadArtifact('path/to/artifact')
  .then((result) => {
    console.log(JSON.stringify(result));
  })
  .catch((error) => {
    console.error(error);
  });

Downloading an Artifact content

The content of the Artifact will be returned as a string.

jfrogClient
  .artifactory()
  .download()
  .downloadArtifact('path/to/artifact')
  .then((result) => {
    console.log(JSON.stringify(result));
  })
  .catch((error) => {
    console.error(error);
  });

Downloading an Artifact to file

jfrogClient
  .artifactory()
  .download()
  .downloadArtifactToFile('path/to/artifact', 'local/path/to/download')
  .then((result) => {
    console.log(JSON.stringify(result));
  })
  .catch((error) => {
    console.error(error);
  });

Downloading an Artifact checksum

jfrogClient
  .artifactory()
  .download()
  .getArtifactChecksum('path/to/artifact')
  .then((result) => {
    console.log('sha1:' + result.sha1 + 'sha256:' + result.sha256 + 'md5:' + result.md5);
  })
  .catch((error) => {
    console.error(error);
  });

Searching by AQL

jfrogClient.artifactory()
    .search()
    .aqlSearch(
        'items.find({' +
        '"repo":"my-repo-name",' +
        '"path":{"$match":"*"}}' +
        ').include("name","repo","path","created").sort({"$desc":["created"]}).limit(10)'
    );
  .then(result => {
    console.log(JSON.stringify(result));
  })
  .catch(error => {
    console.error(error);
  });

Platform

Web Login

Register For Web Login

const sessionId = XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX // UUID
jfrogClient
  .platform()
  .webLogin()
  .registerSessionId(sessionId)
  .then((result) => {
    ...
  })
  .catch((error) => {
    ...
  });

Get Access Token From Web Login

const sessionId = XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX // UUID
jfrogClient
  .platform()
  .webLogin()
  .getToken(sessionId)
  .then((result) => {
    ...
  })
  .catch((error) => {
    ...
  });

Please note that you need to replace 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' with the actual session ID that you've generated for registerSessionId.

Xray Source Control

System

Getting Xsc Version

jfrogClient
  .xsc()
  .system()
  .version()
  .then((result) => {
    console.log(result);
  })
  .catch((error) => {
    console.error(error);
  });

Event

Sending Log Message Event

jfrogClient
  .xsc()
  .event()
  .log({log_level: 'error', source: 'js-client', message: 'error message to report as an event'})
  .catch((error) => {
    console.error(error);
  });

Sending Start Scan Event

jfrogClient
  .xsc()
  .event()
  .startScan({product: 'product', os_platform: 'windows', jfrog_user: 'user-name'})
  .then((result) => {
    console.log(result);
  })
  .catch((error) => {
    console.error(error);
  });

Sending End Scan Event

const scanEvent = {multi_scan_id: 'some-scan-id', event_status: 'completed'}
jfrogClient
  .xsc()
  .event()
  .endScan({product: 'product', os_platform: 'windows', jfrog_user: 'user-name'})
  .then((result) => {
    console.log(result);
  })
  .catch((error) => {
    console.error(error);
  });

Getting Scan Event Details

const multiScanId = XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX // UUID
jfrogClient
  .xsc()
  .event()
  .getScanEvent(multiScanId)
  .then((result) => {
    ...
  })
  .catch((error) => {
    ...
  });

Please note that you need to replace 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' with the actual multi scan ID that you've generated with startScan.