feat: add api request graphql command, UTs, NUTs

Author: WillieRuemmele

README.md

@@ -107,43 +107,76 @@ sf plugins
 
 <!-- commands -->
 
-- [`sf hello world`](#sf-hello-world)
+- [`sf api request graphql`](#sf-api-request-graphql)
+- [`sf api request rest ENDPOINT`](#sf-api-request-rest-endpoint)
 
-## `sf hello world`
+## `sf api request graphql`
 
-Say hello.
+Summary of a command.
 
 ```
 USAGE
-  $ sf hello world [--json] [--flags-dir <value>] [-n <value>]
+  $ sf api request graphql -o <value> --body file [--json] [--flags-dir <value>] [-S Example: report.xlsx | -i]
 
 FLAGS
-  -n, --name=<value>  [default: World] The name of the person you'd like to say hello to.
+  -S, --stream-to-file=Example: report.xlsx  Stream responses to a file.
+  -i, --include                              Include the HTTP response status and headers in the output.
+  -o, --target-org=<value>                   (required) Username or alias of the target org. Not required if the
+                                             `target-org` configuration variable is already set.
+      --body=file                            (required) File to use as the body for the request. Specify "-" to read
+                                             from standard input.
 
 GLOBAL FLAGS
   --flags-dir=<value>  Import flag values from a directory.
   --json               Format output as json.
 
 DESCRIPTION
-  Say hello.
+  Summary of a command.
 
-  Say hello either to the world or someone you know.
+  More information about a command. Don't repeat the summary.
 
 EXAMPLES
-  Say hello to the world:
+  $ sf api request graphql
+```
+
+_See code: [src/commands/api/request/graphql.ts](https://github.com/salesforcecli/plugin-api/blob/v1.0.0/src/commands/api/request/graphql.ts)_
+
+## `sf api request rest ENDPOINT`
+
+Make an authenticated HTTP request to Salesforce REST API and print the response.
+
+```
+USAGE
+  $ sf api request rest ENDPOINT -o username [--flags-dir <value>] [-i | -S Example: report.xlsx] [-X
+    GET|POST|PUT|PATCH|HEAD|DELETE|OPTIONS|TRACE] [-H key:value...] [--body file]
 
-    $ sf hello world
+ARGUMENTS
+  ENDPOINT  Salesforce API endpoint
 
-  Say hello to someone you know:
+FLAGS
+  -H, --header=key:value...                  HTTP header in "key:value" format.
+  -S, --stream-to-file=Example: report.xlsx  Stream responses to a file.
+  -X, --method=<option>                      [default: GET] HTTP method for the request.
+                                             <options: GET|POST|PUT|PATCH|HEAD|DELETE|OPTIONS|TRACE>
+  -i, --include                              Include the HTTP response status and headers in the output.
+  -o, --target-org=username                  (required) Username or alias of the target org. Not required if the
+                                             `target-org` configuration variable is already set.
+      --body=file                            File to use as the body for the request. Specify "-" to read from standard
+                                             input; specify "" for an empty body.
+
+GLOBAL FLAGS
+  --flags-dir=<value>  Import flag values from a directory.
+
+EXAMPLES
+  List information about limits in the org with alias "my-org":
 
-    $ sf hello world --name Astro
+    $ sf api request rest 'services/data/v56.0/limits' --target-org my-org
 
-FLAG DESCRIPTIONS
-  -n, --name=<value>  The name of the person you'd like to say hello to.
+  Get the response in XML format by specifying the "Accept" HTTP header:
 
-    This person can be anyone in the world!
+    $ sf api request rest 'services/data/v56.0/limits' --target-org my-org --header 'Accept: application/xml',
 ```
 
-_See code: [src/commands/hello/world.ts](https://github.com/salesforcecli/plugin-template-sf/blob/1.1.14/src/commands/hello/world.ts)_
+_See code: [src/commands/api/request/rest.ts](https://github.com/salesforcecli/plugin-api/blob/v1.0.0/src/commands/api/request/rest.ts)_
 
 <!-- commandsstop -->

command-snapshot.json

@@ -1,4 +1,12 @@
 [
+  {
+    "alias": [],
+    "command": "api:request:graphql",
+    "flagAliases": [],
+    "flagChars": ["S", "i", "o"],
+    "flags": ["body", "flags-dir", "include", "json", "stream-to-file", "target-org"],
+    "plugin": "@salesforce/plugin-api"
+  },
   {
     "alias": [],
     "command": "api:request:rest",

messages/graphql.md

@@ -0,0 +1,35 @@
+# summary
+
+Summary of a command.
+
+# description
+
+More information about a command. Don't repeat the summary.
+
+# flags.name.summary
+
+Description of a flag.
+
+# flags.name.description
+
+More information about a flag. Don't repeat the summary.
+
+# examples
+
+- <%= config.bin %> <%= command.id %>
+
+# flags.include.summary
+
+Include the HTTP response status and headers in the output.
+
+# flags.header.summary
+
+HTTP header in "key:value" format.
+
+# flags.stream-to-file.summary
+
+Stream responses to a file.
+
+# flags.body.summary
+
+File to use as the body for the request. Specify "-" to read from standard input.

package.json

@@ -9,6 +9,7 @@
     "@salesforce/core": "^8.4.0",
     "@salesforce/kit": "^3.2.1",
     "@salesforce/sf-plugins-core": "^11.3.2",
+    "@salesforce/ts-types": "^2.0.12",
     "ansis": "^3.3.2",
     "got": "^13.0.0",
     "proxy-agent": "^6.4.0"

src/commands/api/request/graphql.ts

@@ -0,0 +1,109 @@
+/*
+ * Copyright (c) 2023, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import fs, { createWriteStream } from 'node:fs';
+import { EOL } from 'node:os';
+import * as os from 'node:os';
+import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+import { Messages, Org, SfError } from '@salesforce/core';
+import { ProxyAgent } from 'proxy-agent';
+import ansis from 'ansis';
+import got from 'got';
+import type { AnyJson } from '@salesforce/ts-types';
+
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@salesforce/plugin-api', 'graphql');
+
+export default class Graphql extends SfCommand<void> {
+  public static readonly summary = messages.getMessage('summary');
+  public static readonly description = messages.getMessage('description');
+  public static readonly examples = messages.getMessages('examples');
+  public static readonly state = 'beta';
+
+  public static readonly flags = {
+    'target-org': Flags.requiredOrg(),
+    'stream-to-file': Flags.string({
+      summary: messages.getMessage('flags.stream-to-file.summary'),
+      helpValue: 'Example: report.xlsx',
+      char: 'S',
+      exclusive: ['include'],
+    }),
+    include: Flags.boolean({
+      char: 'i',
+      summary: messages.getMessage('flags.include.summary'),
+      default: false,
+      exclusive: ['stream-to-file'],
+    }),
+    body: Flags.string({
+      summary: messages.getMessage('flags.body.summary'),
+      helpValue: 'file',
+      required: true,
+    }),
+  };
+
+  public async run(): Promise<void> {
+    const { flags } = await this.parse(Graphql);
+
+    const org = flags['target-org'];
+    const streamFile = flags['stream-to-file'];
+
+    await org.refreshAuth();
+    const apiVersion = await org.retrieveMaxApiVersion();
+
+    const url = `${org.getField<string>(Org.Fields.INSTANCE_URL)}/services/data/v${apiVersion}/graphql`;
+
+    const options = {
+      agent: { https: new ProxyAgent() },
+      headers: {
+        'Content-type': 'application/json',
+        Authorization: `Bearer ${org.getConnection(apiVersion).getConnectionOptions().accessToken!}`,
+        ...{},
+      },
+      body: `{"query":"${fs.readFileSync(flags.body, 'utf8').replaceAll(os.EOL, '\\n')}", "variables": {}}`,
+      throwHttpErrors: false,
+      followRedirect: false,
+    };
+
+    if (streamFile) {
+      const responseStream = got.stream.post(url, options);
+      const fileStream = createWriteStream(streamFile);
+      responseStream.pipe(fileStream);
+
+      fileStream.on('finish', () => this.log(`File saved to ${streamFile}`));
+      fileStream.on('error', (error) => {
+        throw SfError.wrap(error);
+      });
+      responseStream.on('error', (error) => {
+        throw SfError.wrap(error);
+      });
+    } else {
+      const res = await got.post(url, options);
+
+      // Print HTTP response status and headers.
+      if (flags.include) {
+        let httpInfo = `HTTP/${res.httpVersion} ${res.statusCode} ${EOL}`;
+
+        for (const [header] of Object.entries(res.headers)) {
+          httpInfo += `${ansis.blue.bold(header)}: ${res.headers[header] as string}${EOL}`;
+        }
+        this.log(httpInfo);
+      }
+
+      try {
+        // Try to pretty-print JSON response.
+        this.styledJSON(JSON.parse(res.body) as AnyJson);
+      } catch (err) {
+        // If response body isn't JSON, just print it to stdout.
+        this.log(res.body);
+      }
+
+      if (res.statusCode >= 400) {
+        process.exitCode = 1;
+      }
+    }
+  }
+}

src/commands/api/request/rest.ts

@@ -67,7 +67,7 @@ export class Rest extends SfCommand<void> {
     }),
   };
 
-  private static getHeaders(keyValPair: string[]): Headers {
+  public static getHeaders(keyValPair: string[]): Headers {
     const headers: { [key: string]: string } = {};
 
     for (const header of keyValPair) {

test/commands/api/request/graphql.nut.ts

@@ -0,0 +1,131 @@
+/*
+ * Copyright (c) 2020, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import { join } from 'node:path';
+import fs from 'node:fs';
+import { config, expect } from 'chai';
+import { execCmd, TestSession } from '@salesforce/cli-plugins-testkit';
+
+config.truncateThreshold = 0;
+
+describe('api:request:graphql NUT', () => {
+  let testSession: TestSession;
+
+  before(async () => {
+    testSession = await TestSession.create({
+      scratchOrgs: [
+        {
+          config: 'config/project-scratch-def.json',
+          setDefault: true,
+        },
+      ],
+      project: { gitClone: 'https://github.com/trailheadapps/dreamhouse-lwc' },
+      devhubAuthStrategy: 'AUTO',
+    });
+    fs.writeFileSync(
+      join(testSession.project.dir, 'standard.txt'),
+      `query accounts {
+  uiapi {
+    query {
+      Account {
+        edges {
+          node {
+            Id
+            Name {
+              value
+            }
+          }
+        }
+      }
+    }
+  }
+}
+`
+    );
+
+    fs.writeFileSync(
+      join(testSession.project.dir, 'noResults.txt'),
+      `query Address {
+  uiapi {
+    query {
+      Address {
+        edges {
+          node {
+            Id
+          }
+        }
+      }
+    }
+  }
+}
+`
+    );
+  });
+
+  after(async () => {
+    await testSession?.clean();
+  });
+
+  describe('std out', () => {
+    it('get result in json format', () => {
+      const result = execCmd('api request graphql --body standard.txt').shellOutput.stdout;
+
+      // make sure we got a JSON object back
+      const parsed = JSON.parse(result) as Record<string, unknown>;
+      expect(Object.keys(parsed)).to.have.length;
+
+      // @ts-expect-error graphql response, just access what we need without typing it
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      expect(parsed.data!.uiapi.query.Account.edges.length).to.equal(1);
+      expect(parsed.errors).to.deep.equal([]);
+    });
+
+    it('get no results correctly', () => {
+      const result = execCmd('api request graphql --body noResults.txt').shellOutput.stdout;
+
+      // make sure we got a JSON object back
+      const parsed = JSON.parse(result) as Record<string, unknown>;
+      expect(Object.keys(parsed)).to.have.length;
+      // @ts-expect-error graphql response, just access what we need without typing it
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      expect(parsed.data!.uiapi.query.Address.edges.length).to.equal(0);
+      expect(parsed.errors).to.deep.equal([]);
+    });
+  });
+
+  describe('stream-to-file', () => {
+    it('get result in json format', () => {
+      execCmd('api request graphql --body standard.txt --stream-to-file out.txt').shellOutput.stdout;
+
+      // make sure we got a JSON object back
+      const parsed = JSON.parse(fs.readFileSync(join(testSession.project.dir, 'out.txt'), 'utf8')) as Record<
+        string,
+        unknown
+      >;
+      expect(Object.keys(parsed)).to.have.length;
+      // @ts-expect-error graphql response, just access what we need without typing it
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      expect(parsed.data!.uiapi.query.Account.edges.length).to.equal(1);
+      expect(parsed.errors).to.deep.equal([]);
+    });
+
+    it('get no results correctly', () => {
+      execCmd('api request graphql --body noResults.txt --stream-to-file empty.txt').shellOutput.stdout;
+
+      // make sure we got a JSON object back
+      const parsed = JSON.parse(fs.readFileSync(join(testSession.project.dir, 'empty.txt'), 'utf8')) as Record<
+        string,
+        unknown
+      >;
+      expect(Object.keys(parsed)).to.have.length;
+      // @ts-expect-error graphql response, just access what we need without typing it
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      expect(parsed.data!.uiapi.query.Address.edges.length).to.equal(0);
+      expect(parsed.errors).to.deep.equal([]);
+    });
+  });
+});