Documentation

Socket JavaScript SDK

Suggest Edits

The Socket JavaScript SDK is a powerful tool that simplifies the use of our REST API in your scripts. It comes with types included, making your coding process smoother and more efficient. This SDK allows you to harness the full potential of Socket's features in a more tailored way, giving you the flexibility to customize as per your specific needs. It's like having a Swiss Army knife for your application security, ready to be wielded in the unique way that suits you best.

Usage

npm install @socketsecurity/sdk

ESM / TypeScript

import { SocketSdk } from '@socketsecurity/sdk'
const client = new SocketSdk('yourApiKeyHere')
const res = await client.getQuota()
if (res.success) {
  // Will output { quota: 123 } if the quota you have left is 123
  console.log(res.data)
}

CommonJS

const { SocketSdk } = require('@socketsecurity/sdk')

SocketSdk Methods

Package methods

  • getIssuesByNPMPackage(packageName, version)
    • packageName: A string representing the name of the npm package you want the issues for
    • version: A string representing the version of the npm package to return the issues for
  • getScoreByNPMPackage(packageName, version)
    • packageName: A string representing the name of the npm package you want the score for
    • version: A string representing the version of the npm package to return the score for

Report methods

  • createReportFromFilePaths(filePaths, pathsRelativeTo=., [issueRules])
    • filePaths: An array of absolute or relative string paths to package.json and any corresponding package-lock.json files
    • pathsRelativeTo: A string path that the absolute paths filePaths are relative to. This to calculate where in your project the package.json/package-lock.json files lives
    • issueRules: An object that follows the format of the socket.yml issue rules. Keys being issue names, values being a boolean that activates or deactivates it. Is applied on top of default config and organization config.
  • getReportList()
  • getReportSupportedFiles()
  • getReport(id)
    • id: A string representing the id of a created report

Utility methods

  • getQuota()
  • getOrganizations()
  • postSettings(selectors)
    • selectors: An array of settings selectors, e.g. [{ organization: 'id' }]

Additional exports

  • createUserAgentFromPkgJson(pkgJson)
    • pkgJson: The content of the package.json you want to create a User-Agent string for

Advanced

Specifying custom user agent

The SocketSdk constructor accepts an options object as its second argument and there a userAgent key with a string value can be specified. If specified then that user agent will be prepended to the SDK user agent. See this example:

const client = new SocketSdk('yourApiKeyHere', {
  userAgent: 'example/1.2.3 (http://example.com/)'
})

Which results in the HTTP User-Agent header:

User-Agent: example/1.2.3 (http://example.com/) socketsecurity-sdk/0.5.2 (https://github.com/SocketDev/socket-sdk-js)

To easily create a user agent for your code you can use the additional export createUserAgentFromPkgJson() like this, assuming pkgJson contains your parsed package.json:

const client = new SocketSdk('yourApiKeyHere', {
  userAgent: createUserAgentFromPkgJson(pkgJson)
})

Specifying a custom user agent is good practice when shipping a piece of code that others can use to make requests. Eg. Socket CLI uses this option to identify requests coming from it + mentioning which version of it that is used.

See also

Updated 2 months ago