gsweet

Summary

A project for gathering the core methods and tools for making it easier to write scripts across all the products in the gSuite.

Installation

npm i gsweet --save

Basic Use

Once you have your authentication JSON file set up in a file named .env.json you require the package and call the auth() function

const GSweet = require("gsweet");
const gsweet = new Gsweet();
const { driveOps } = gsweet;
const { sheetOps } = gsweet;

In the above example the lack of a parameter to the new GSweet constructor is telling the package to look for .env.json at the root of the project. If your credentials file lives somewhere else you can just pass in a relative or absolute path like this

const gsweet = new Gsweet({pathOrVarName:"/Users/your-user-name/dev/ENV_VARS/gsweet.env.json", useExistingEnvVar:false);
const { driveOps } = gsweet;
const { sheetOps } = gsweet;

The second parameter supports using an environment variable that already contains the proper credential string. For example, if you're using Heroku and you have a config var named "GSWEET" the call would be

const gsweet = new GSweet({ pathOrVarName: "GSWEET", useExistingEnvVar: true });

The code that runs loads the JSON file and parses the top level objects into environment variables needed by this package.

A full example usage of the package might look like this

cconst gsweet = new Gsweet({pathOrVarName:"/Users/your-user-name/dev/ENV_VARS/gsweet.env.json", useExistingEnvVar:false);
const { driveOps, sheetOps } = gsweet;

const main = async () => {
  // Drive Examples
  const TEST_FILE = "<name of sheet in your drive>";
  const result = await driveOps.getFiles({
    withName: TEST_FILE,
    exactMatch: true
  });
  console.log(result);

  // Sheet Examples
  const sheetRange = {
    id: "<google id of a sheet in your drive>",
    range: "Sheet1!A1",
    data: [["Test1"], ["Test2"]]
  };
  const result2 = await sheetOps.setRangeData(sheetRange);
  console.log(result2.config.data.values); // just showing the values passed in
  console.log("Num Cells Updated:", result2.data.updatedCells);
};
main();

Authentication

If you clone this repo it will not contain the needed authorization pieces. You will need to create a JSON file with the following structure:

"gsweet":{
   "client_secrets": {
    },
    "drive_credentials": {
    },
    "sheet_credentials": {
    }
  }
}

If you want to store all of this in an .env file you will need to turn it into a properly escaped string. A partial example looks like this. Note that all but the starting and ending quote marks need to be escaped. JSON wants double quotes so you can't substitute single quotes.

"gsweet":"{\"client_secrets\":{\"installed\":{\"client_id\"..."

You will need to fill in those objects with the expected json that Google requires. Google has a quick-start on how to create all of these credentials. You can see a full example of the JSOn file in the Reference section of this Readme.

Testing

This package contains both unit tests and integration tests. The integration tests are fragile since they require access to specific files and folders in google drive. The constants for these files are stored in the test-data/integration.json. Modify that document to contain the names and ids for your files. The expected structure of the test data is test-folder

---node-test-subfolder
  |---doc-in-subfolder
  |---sheet-in-subfolder
  node-test-sheet
  node-test-doc

The top of the integration test files also uses create-env to load credentials. You will need to change that path to point to your credentials json file.

This project is set up such that unit tests will be written with a test.js suffix and integration tests will end with testi.js. You can run unit tests with npm test -- the unit tests
npm run test:int -- the integration tests
npm run test:all -- both unit and integration tests

Reference on Using the Google Apis

This is information for anyone contributing to (rather than using) this project.

GoogleApis npm package

Check out some Drive Samples.

The Drive API

Additional Documentation

This project uses JSDoc comments. If you want to generate the HTML documentation in an /out folder at the root of the project use:
npm run doc

Reference

Full .json.env example

{
  "gsweet":{
    "client_secrets": {
        "installed": {
          "client_id": "your id goes here",
          "project_id": "your project id",
          "auth_uri": "https://accounts.google.com/o/oauth2/auth",
          "token_uri": "https://accounts.google.com/o/oauth2/token",
          "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
          "client_secret": "your client secret",
          "redirect_uris": [
            "urn:ietf:wg:oauth:2.0:oob",
            "http://localhost"
          ]
        }
      },
      "drive_credentials": {
        "access_token": "a really long token",
        "refresh_token": "a shorter token",
        "token_type": "Bearer",
        "expiry_date": 123
      },
      "sheet_credentials": {
        "access_token": "your token",
        "refresh_token": "the refresh toeken",
        "scope": "https://www.googleapis.com/auth/spreadsheets",
        "token_type": "Bearer",
        "expiry_date": 123
      }
  }
}

Documentation on GitHub

See the GitHub documentation for the list of available modules, functions, function signatures, and usage examples.