Improve User-Agent of SDK

Author: Pelle Wessman

README.md

@@ -60,8 +60,42 @@ const { SocketSdk } = require('@socketsecurity/sdk')
 
 * `getQuota()`
 
+## 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:
+
+```js
+const client = new SocketSdk('yourApiKeyHere', {
+  userAgent: 'example/1.2.3 (http://example.com/)'
+})
+```
+
+Which results in the [HTTP `User-Agent` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent):
+
+```
+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`:
+
+```js
+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. [our CLI](https://github.com/SocketDev/socket-cli-js) uses this option to identify requests coming from it + mentioning which version of it that is used.
+
 ## See also
 
 * [Socket API Reference](https://docs.socket.dev/reference)
 * [Socket.dev](https://socket.dev/)
 * [Socket GitHub App](https://github.com/apps/socket-security)
+* [Socket CLI](https://github.com/SocketDev/socket-cli-js)

index.js

@@ -4,6 +4,8 @@ const path = require('node:path')
 
 const { ErrorWithCause } = require('pony-cause')
 
+const pkg = require('./package.json')
+
 /**
  * @template {keyof import('./types/api').operations} T
  * @typedef {import('./types/api-helpers').OpReturnType<import('./types/api').operations[T]>} SocketSdkReturnType
@@ -23,6 +25,7 @@ const { ErrorWithCause } = require('pony-cause')
  * @typedef SocketSdkOptions
  * @property {import('got').Agents} [agent]
  * @property {string} [baseUrl]
+ * @property {string} [userAgent]
  */
 
 class SocketSdk {
@@ -44,12 +47,16 @@ class SocketSdk {
     const {
       agent,
       baseUrl = 'https://api.socket.dev/v0/',
+      userAgent,
     } = options
 
     this.#gotOptions = {
       prefixUrl: baseUrl,
       retry: { limit: 0 },
       username: apiKey,
+      headers: {
+        'user-agent': (userAgent ? userAgent + ' ' : '') + createUserAgentFromPkgJson(pkg),
+      },
       ...(agent ? { agent } : {}),
     }
   }
@@ -243,4 +250,15 @@ function ensureObject (value) {
   return !!(value && typeof value === 'object' && !Array.isArray(value))
 }
 
-module.exports = { SocketSdk }
+/**
+ * @param {{ name: string, version: string, homepage?: string }} pkgData Package.json data to base the User-Agent on
+ * @returns {string}
+ */
+function createUserAgentFromPkgJson (pkgData) {
+  return `${pkgData.name.replace('@', '').replace('/', '-')}/${pkgData.version}` + (pkgData.homepage ? ` (${pkgData.homepage})` : '')
+}
+
+module.exports = {
+  createUserAgentFromPkgJson,
+  SocketSdk,
+}