├── .prettierignore ├── .editorconfig ├── CHANGELOG.md ├── tests ├── expected │ ├── extensions.js │ └── basic.js └── test.js ├── .github └── workflows │ └── ci.yaml ├── types.d.ts ├── LICENSE ├── package.json ├── .gitignore ├── index.js └── README.md /.prettierignore: -------------------------------------------------------------------------------- 1 | package.json 2 | package-lock.json 3 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_style = space 5 | indent_size = 2 6 | end_of_line = lf 7 | charset = utf-8 8 | trim_trailing_whitespace = true 9 | insert_final_newline = true 10 | 11 | [*.md] 12 | trim_trailing_whitespace = false -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. 4 | 5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 7 | 8 | ## [Unreleased] 9 | 10 | ## [1.0.0] 11 | 12 | ### Added 13 | 14 | - Initial release! 15 | -------------------------------------------------------------------------------- /tests/expected/extensions.js: -------------------------------------------------------------------------------- 1 | // Source Google Doc: https://docs.google.com/document/d/1_v0gAswpNnGnDqAx7cU_1bFEK8J7fi8EBvfKvgGZubc/edit 2 | module.exports = { 3 | url_key: 'Wikipedia', 4 | url_list: [ 5 | 'Wikipedia', 6 | 'MetaFilter', 7 | 'TVTropes', 8 | ], 9 | }; 10 | -------------------------------------------------------------------------------- /.github/workflows/ci.yaml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: [push] 4 | 5 | jobs: 6 | test: 7 | name: Node.js v${{ matrix.node-version }} 8 | runs-on: ubuntu-latest 9 | 10 | strategy: 11 | fail-fast: false 12 | matrix: 13 | node-version: [12, 14, 16] 14 | 15 | steps: 16 | - name: Checkout the repo 17 | uses: actions/checkout@v3 18 | 19 | - name: Use Node.js v${{ matrix.node-version }} 20 | uses: actions/setup-node@v3 21 | with: 22 | node-version: ${{ matrix.node-version }} 23 | cache: 'npm' 24 | 25 | - name: npm install 26 | run: npm ci 27 | 28 | - name: Set up Google auth 29 | uses: google-github-actions/auth@v0 30 | with: 31 | credentials_json: ${{ secrets.GOOGLE_CREDENTIALS }} 32 | 33 | - name: Run tests 34 | run: npm test 35 | -------------------------------------------------------------------------------- /types.d.ts: -------------------------------------------------------------------------------- 1 | import { GoogleApis, docs_v1 } from 'googleapis'; 2 | 3 | export interface BaseDocToArchieMLOptions { 4 | documentId: docs_v1.Params$Resource$Documents$Get['documentId']; 5 | } 6 | 7 | export interface AuthDocToArchieMLOptions extends BaseDocToArchieMLOptions { 8 | auth: docs_v1.Params$Resource$Documents$Get['auth']; 9 | } 10 | 11 | export interface ClientDocToArchieMLOptions extends BaseDocToArchieMLOptions { 12 | client: docs_v1.Docs; 13 | } 14 | 15 | export interface GoogleDocToArchieMLOptions extends BaseDocToArchieMLOptions { 16 | google: GoogleApis; 17 | } 18 | 19 | export type DocToArchieMLOptions = 20 | | AuthDocToArchieMLOptions 21 | | ClientDocToArchieMLOptions 22 | | GoogleDocToArchieMLOptions; 23 | 24 | declare function docToArchieML({ 25 | auth, 26 | client, 27 | documentId, 28 | google, 29 | }: DocToArchieMLOptions): Promise; 30 | 31 | export { docToArchieML }; 32 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 Ryan Murphy 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /tests/test.js: -------------------------------------------------------------------------------- 1 | const { strict: assert } = require('assert'); 2 | const { google } = require('googleapis'); 3 | const { docToArchieML } = require('../'); 4 | 5 | const expectedBasicOutput = require('./expected/basic'); 6 | const expectedExtensionsOutput = require('./expected/extensions'); 7 | 8 | const basicDocumentId = 9 | process.env.BASIC_DOCUMENT_ID || 10 | '1coln1etP5rT1MqmNtRT7lToGtCi1EAsDVzC5aq0LsIc'; 11 | const extensionsDocumentId = 12 | process.env.EXTENSIONS_DOCUMENT_ID || 13 | '1_v0gAswpNnGnDqAx7cU_1bFEK8J7fi8EBvfKvgGZubc'; 14 | 15 | describe('@newswire/doc-to-archieml', () => { 16 | let auth; 17 | 18 | before(async () => { 19 | auth = await google.auth.getClient({ 20 | scopes: ['https://www.googleapis.com/auth/documents.readonly'], 21 | }); 22 | }); 23 | 24 | it('should return a valid JavaScript object of basic ArchieML data', async () => { 25 | const actual = await docToArchieML({ 26 | documentId: basicDocumentId, 27 | auth, 28 | }); 29 | 30 | assert.deepStrictEqual(actual, expectedBasicOutput); 31 | }); 32 | 33 | it('should return a valid JavaScript object of extended ArchieML data', async () => { 34 | const actual = await docToArchieML({ 35 | documentId: extensionsDocumentId, 36 | auth, 37 | }); 38 | 39 | assert.deepStrictEqual(actual, expectedExtensionsOutput); 40 | }); 41 | }); 42 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@newswire/doc-to-archieml", 3 | "version": "1.0.0", 4 | "description": "Convert an ArchieML-formatted Google Doc directly into usable data using the Google Docs API.", 5 | "main": "index.js", 6 | "types": "types.d.ts", 7 | "files": [ 8 | "index.js", 9 | "types.d.ts" 10 | ], 11 | "scripts": { 12 | "docs": "doctoc README.md --github", 13 | "git-pre-commit": "precise-commits", 14 | "prerelease": "yarn test", 15 | "release": "git push && git push --tags && yarn publish", 16 | "test": "mocha --timeout 5000 tests/test.js" 17 | }, 18 | "repository": { 19 | "type": "git", 20 | "url": "git+https://github.com/rdmurphy/doc-to-archieml.git" 21 | }, 22 | "keywords": [ 23 | "googleapis", 24 | "archieml", 25 | "templating", 26 | "googledocs" 27 | ], 28 | "author": "Ryan Murphy", 29 | "license": "MIT", 30 | "bugs": { 31 | "url": "https://github.com/rdmurphy/doc-to-archieml/issues" 32 | }, 33 | "homepage": "https://github.com/rdmurphy/doc-to-archieml#readme", 34 | "dependencies": { 35 | "archieml": "^0.4.2", 36 | "googleapis": "^39.2.0" 37 | }, 38 | "devDependencies": { 39 | "@newswire/prettier-config": "^1.0.0", 40 | "@zeit/git-hooks": "^0.1.4", 41 | "doctoc": "^2.0.1", 42 | "mocha": "^8.1.0", 43 | "precise-commits": "^1.0.2", 44 | "prettier": "^1.17.1" 45 | }, 46 | "prettier": "@newswire/prettier-config" 47 | } 48 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | lerna-debug.log* 8 | 9 | # Diagnostic reports (https://nodejs.org/api/report.html) 10 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 11 | 12 | # Runtime data 13 | pids 14 | *.pid 15 | *.seed 16 | *.pid.lock 17 | 18 | # Directory for instrumented libs generated by jscoverage/JSCover 19 | lib-cov 20 | 21 | # Coverage directory used by tools like istanbul 22 | coverage 23 | 24 | # nyc test coverage 25 | .nyc_output 26 | 27 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 28 | .grunt 29 | 30 | # Bower dependency directory (https://bower.io/) 31 | bower_components 32 | 33 | # node-waf configuration 34 | .lock-wscript 35 | 36 | # Compiled binary addons (https://nodejs.org/api/addons.html) 37 | build/Release 38 | 39 | # Dependency directories 40 | node_modules/ 41 | jspm_packages/ 42 | 43 | # TypeScript v1 declaration files 44 | typings/ 45 | 46 | # Optional npm cache directory 47 | .npm 48 | 49 | # Optional eslint cache 50 | .eslintcache 51 | 52 | # Optional REPL history 53 | .node_repl_history 54 | 55 | # Output of 'npm pack' 56 | *.tgz 57 | 58 | # Yarn Integrity file 59 | .yarn-integrity 60 | 61 | # dotenv environment variables file 62 | .env 63 | .env.test 64 | 65 | # parcel-bundler cache (https://parceljs.org/) 66 | .cache 67 | 68 | # next.js build output 69 | .next 70 | 71 | # nuxt.js build output 72 | .nuxt 73 | 74 | # vuepress build output 75 | .vuepress/dist 76 | 77 | # Serverless directories 78 | .serverless/ 79 | 80 | # FuseBox cache 81 | .fusebox/ 82 | 83 | # DynamoDB Local files 84 | .dynamodb/ 85 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | // packages 2 | const { load } = require('archieml'); 3 | const { google: googleApisInstance } = require('googleapis'); 4 | 5 | function readParagraphElement(element) { 6 | // pull out the text 7 | const textRun = element.textRun; 8 | 9 | // sometimes it's not there, skip this all if so 10 | if (textRun) { 11 | // sometimes the content isn't there, and if so, make it an empty string 12 | const content = textRun.content || ''; 13 | 14 | // step through optional text styles to check for an associated URL 15 | if (!textRun.textStyle) return content; 16 | if (!textRun.textStyle.link) return content; 17 | if (!textRun.textStyle.link.url) return content; 18 | 19 | // if we got this far there's a URL key, grab it... 20 | const url = textRun.textStyle.link.url; 21 | 22 | // ...but sometimes that's empty too 23 | if (url) { 24 | return `${content}`; 25 | } else { 26 | return content; 27 | } 28 | } else { 29 | return ''; 30 | } 31 | } 32 | 33 | function readElements(document) { 34 | // prepare the text holder 35 | let text = ''; 36 | 37 | // check if the body key and content key exists, and give up if not 38 | if (!document.body) return text; 39 | if (!document.body.content) return text; 40 | 41 | // loop through each content element in the body 42 | document.body.content.forEach(element => { 43 | if (element.paragraph) { 44 | // get the paragraph within the element 45 | const paragraph = element.paragraph; 46 | 47 | // this is a list 48 | const needsBullet = paragraph.bullet != null; 49 | 50 | if (paragraph.elements) { 51 | // all values in the element 52 | const values = paragraph.elements; 53 | 54 | values.forEach((value, idx) => { 55 | // we only need to add a bullet to the first value, so we check 56 | const isFirstValue = idx === 0; 57 | 58 | // prepend an asterisk if this is a list item 59 | const prefix = needsBullet && isFirstValue ? '* ' : ''; 60 | 61 | // concat the text 62 | text += `${prefix}${readParagraphElement(value)}`; 63 | }); 64 | } 65 | } 66 | }); 67 | 68 | return text; 69 | } 70 | 71 | async function docToArchieML({ 72 | auth, 73 | client, 74 | documentId, 75 | google = googleApisInstance, 76 | }) { 77 | // create docs client if not provided 78 | if (!client) { 79 | client = google.docs({ 80 | version: 'v1', 81 | auth, 82 | }); 83 | } 84 | 85 | // pull the data out of the doc 86 | const { data } = await client.documents.get({ 87 | documentId, 88 | }); 89 | 90 | // convert the doc's content to text ArchieML will understand 91 | const text = readElements(data); 92 | 93 | // pass text to ArchieML and return results 94 | return load(text); 95 | } 96 | 97 | module.exports = { docToArchieML }; 98 | -------------------------------------------------------------------------------- /tests/expected/basic.js: -------------------------------------------------------------------------------- 1 | // Source Google Doc: https://docs.google.com/document/d/1coln1etP5rT1MqmNtRT7lToGtCi1EAsDVzC5aq0LsIc/edit 2 | module.exports = { 3 | '1': 'value', 4 | '2': 'value', 5 | '3': 'value', 6 | '4': 'value', 7 | '5': 'value', 8 | key: 'This is a value', 9 | '☃': 'Unicode Snowman for you and you and you!', 10 | a: 'lowercase a', 11 | A: 'uppercase A', 12 | key_leading_spaces: 'value', 13 | colors: { 14 | red: '#f00', 15 | green: '#0f0', 16 | blue: '#00f', 17 | reds: { 18 | crimson: '#dc143c', 19 | darkred: '#8b0000', 20 | }, 21 | blues: { 22 | cornflowerblue: '#6495ed', 23 | darkblue: '#00008b', 24 | }, 25 | }, 26 | colors_object: { 27 | red: '#f00', 28 | green: '#0f0', 29 | blue: '#00f', 30 | }, 31 | numbers: { 32 | one: '1', 33 | ten: '10', 34 | 'one-hundred': '100', 35 | }, 36 | arrayName: [ 37 | { 38 | name: 'Amanda', 39 | age: '26', 40 | }, 41 | { 42 | name: 'Tessa', 43 | age: '30', 44 | }, 45 | ], 46 | days: [ 47 | 'Sunday', 48 | 'Monday', 49 | 'Tuesday', 50 | 'Wednesday', 51 | 'Thursday', 52 | 'Friday', 53 | 'Saturday', 54 | ], 55 | array: [ 56 | { 57 | subarray: [ 58 | { 59 | subsubarray: [ 60 | { 61 | key: 'value', 62 | }, 63 | ], 64 | }, 65 | ], 66 | }, 67 | ], 68 | nested_days: [ 69 | { 70 | name: 'Monday', 71 | tasks: ['Clean dishes', 'Pick up room'], 72 | }, 73 | { 74 | name: 'Tuesday', 75 | tasks: ['Buy milk'], 76 | }, 77 | ], 78 | books: [ 79 | { 80 | type: 'kicker', 81 | value: 'Books you should read', 82 | }, 83 | { 84 | type: 'score', 85 | value: '★★★★★!!!', 86 | }, 87 | { 88 | type: 'title', 89 | value: 'Wuthering Heights', 90 | }, 91 | { 92 | type: 'author', 93 | value: 'Emily Brontë', 94 | }, 95 | { 96 | type: 'title', 97 | value: 'Middlemarch', 98 | }, 99 | { 100 | type: 'author', 101 | value: 'George Eliot', 102 | }, 103 | { 104 | type: 'score', 105 | value: '★★★★☆', 106 | }, 107 | ], 108 | text: [ 109 | { 110 | type: 'text', 111 | value: 'I can type words here...', 112 | }, 113 | { 114 | type: 'text', 115 | value: 'And separate them into different paragraphs without tags.', 116 | }, 117 | ], 118 | events: [ 119 | { 120 | type: 'header', 121 | value: 'My Birthday', 122 | }, 123 | { 124 | type: 'date', 125 | value: 'August 20th, 1990', 126 | }, 127 | { 128 | type: 'image', 129 | value: { 130 | src: 'http://example.com/photo.png', 131 | alt: 'Family Photo', 132 | }, 133 | }, 134 | { 135 | type: 'header', 136 | value: 'High School Graduation', 137 | }, 138 | { 139 | type: 'date', 140 | value: 'June 4th, 2008', 141 | }, 142 | ], 143 | multi_line_key: 'value\n More value\n\nEven more value', 144 | arrays: { 145 | complex: [ 146 | { 147 | key: 'value\nmore value', 148 | }, 149 | ], 150 | simple: ['value\nmore value'], 151 | }, 152 | escape_key: 'value\n:end', 153 | ignore_key: 'value', 154 | }; 155 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

2 | @newswire/doc-to-archieml 3 |

4 |

5 | CI 6 | npm 7 | install size 8 |

9 | 10 | `@newswire/doc-to-archieml` is a simple wrapper around the [Google Docs API](https://developers.google.com/docs/api/) and [ArchieML](http://archieml.org) for converting the contents of a Google Doc into a ArchieML-produced data structure. 11 | 12 | ## Key features 13 | 14 | - ⚙️ Produces identical output to **[ArchieML's example Google Drive export method](https://github.com/newsdev/archieml-js/tree/master#using-with-google-documents)** (including support for converting links to `` tags) without the use of an HTML parser 15 | - 👩‍🔧 Does not expect any particular method of authenticating with Google — **use the authenticated Google API instance, Google Docs client or [authentication method](https://github.com/googleapis/google-api-nodejs-client#authentication-and-authorization) you are already using** 16 | 17 | ## Installation 18 | 19 | `@newswire/doc-to-archieml` requires a version of Node.js **8 or higher**. It is available via `npm`. 20 | 21 | ```sh 22 | npm install --save-dev @newswire/doc-to-archieml 23 | # or 24 | yarn add --dev @newswire/doc-to-archieml 25 | ``` 26 | 27 | ## Table of contents 28 | 29 | 30 | 31 | 32 | - [Usage](#usage) 33 | - [Authentication](#authentication) 34 | - [1) Passing authentication](#1-passing-authentication) 35 | - [2) Passing an authenticated Google Docs API client](#2-passing-an-authenticated-google-docs-api-client) 36 | - [3) Passing an authenticated Google APIs instance](#3-passing-an-authenticated-google-apis-instance) 37 | - [Contributing](#contributing) 38 | - [License](#license) 39 | 40 | 41 | 42 | ## Usage 43 | 44 | `@newswire/doc-to-archieml` exports a single function - `docToArchieML`. 45 | 46 | ```js 47 | const { docToArchieML } = require('@newswire/doc-to-archieml'); 48 | const { google } = require('googleapis'); 49 | 50 | async function main() { 51 | // this method looks for the GCLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS 52 | // environment variables to establish authentication 53 | const auth = await google.auth.getClient({ 54 | scopes: ['https://www.googleapis.com/auth/documents.readonly'], 55 | }); 56 | 57 | // pass in the valid authentication and ID of the document you want to process 58 | const results = await docToArchieML({ documentId: '...', auth }); 59 | 60 | console.log(results); // `results` is your ArchieML-produced JavaScript object 61 | } 62 | 63 | main().catch(console.error); 64 | ``` 65 | 66 | ## Authentication 67 | 68 | `docToArchieML` has one required parameter — `documentId`. But the authentication you provide with the Google API may be handled in one of the three ways detailed below. 69 | 70 | _Acquiring_ this authentication is beyond the scope of this project's documentation, but two good starting points are [Google's official Node.js quickstart guide for the Google Docs API](https://developers.google.com/docs/api/quickstart/nodejs) and the [client library's authentication documentation](https://github.com/googleapis/google-api-nodejs-client#authentication-and-authorization). 71 | 72 | ### 1) Passing authentication 73 | 74 | `docToArchieML` doesn't limit authentication to only OAuth2 (although it certainly supports it!) and will accept any authenticated client that the Google Docs API supports. 75 | 76 | After establishing authentication [using one of the methods](https://github.com/googleapis/google-api-nodejs-client#authentication-and-authorization) supported by `googleapis`, you can pass this auth directly to `docToArchieML` and it'll handle the rest. 77 | 78 | ```js 79 | const { docToArchieML } = require('@newswire/doc-to-archieml'); 80 | const { google } = require('googleapis'); 81 | 82 | async function main() { 83 | // this method looks for the GCLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS 84 | // environment variables to establish authentication 85 | const auth = await google.auth.getClient({ 86 | scopes: ['https://www.googleapis.com/auth/documents.readonly'], 87 | }); 88 | 89 | // pass in the valid authentication, which is used to create a Google Docs API client internally 90 | const results = await docToArchieML({ documentId: '...', auth }); 91 | } 92 | 93 | main().catch(console.error); 94 | ``` 95 | 96 | > (This example uses the [service-to-service authentication](https://github.com/googleapis/google-api-nodejs-client#service-to-service-authentication) method.) 97 | 98 | ### 2) Passing an authenticated Google Docs API client 99 | 100 | Maybe you've been working with the Google Docs API and have already set up an authenticated instance of the Google Docs API client that has access to the docs you'd like to work with. `docToArchieML` will accept that and use it! 101 | 102 | ```js 103 | const { docToArchieML } = require('@newswire/doc-to-archieml'); 104 | const { google } = require('googleapis'); 105 | 106 | async function main() { 107 | // this method looks for the GCLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS 108 | // environment variables to establish authentication 109 | const auth = await google.auth.getClient({ 110 | scopes: ['https://www.googleapis.com/auth/documents.readonly'], 111 | }); 112 | 113 | // create your own Google Docs API client 114 | const client = google.docs({ 115 | version: 'v1', 116 | auth, 117 | }); 118 | 119 | // pass in the authenticated Google Docs API client 120 | const results = await docToArchieML({ documentId: '...', client }); 121 | } 122 | 123 | main().catch(console.error); 124 | ``` 125 | 126 | > (This example uses the [service-to-service authentication](https://github.com/googleapis/google-api-nodejs-client#service-to-service-authentication) method.) 127 | 128 | ### 3) Passing an authenticated Google APIs instance 129 | 130 | Maybe you've been using multiple Google API services and have [set authentication across all Google APIs globally](https://github.com/googleapis/google-api-nodejs-client#setting-global-or-service-level-auth). `docToArchieML` can accept the authenticated `googleApisInstance` and use that to create the Google Docs API client - no passing of `auth` necessary. 131 | 132 | ```js 133 | const { docToArchieML } = require('@newswire/doc-to-archieml'); 134 | const { google } = require('googleapis'); 135 | 136 | async function main() { 137 | // this method looks for the GCLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS 138 | // environment variables to establish authentication 139 | const auth = await google.auth.getClient({ 140 | scopes: ['https://www.googleapis.com/auth/documents.readonly'], 141 | }); 142 | 143 | // set auth as a global default 144 | google.options({ auth }); 145 | 146 | // pass in the GoogleApisInstance, which will be used to connect to the Google Docs API 147 | const results = await docToArchieML({ documentId: '...', google }); 148 | } 149 | 150 | main().catch(console.error); 151 | ``` 152 | 153 | > (This example uses the [service-to-service authentication](https://github.com/googleapis/google-api-nodejs-client#service-to-service-authentication) method.) 154 | 155 | ## Contributing 156 | 157 | First clone the repo to your local device and install the dependencies. 158 | 159 | ```sh 160 | yarn 161 | ``` 162 | 163 | After making any changes, you'll need to run the tests. But this is a little tricky because we perform an integration test against live Google Doc files. To make the tests work for you locally, you'll need to do a few extra steps. 164 | 165 | First make a copy of the two test doc files: 166 | 167 | [Click here to make a copy of the basic test doc file](https://docs.google.com/document/d/1coln1etP5rT1MqmNtRT7lToGtCi1EAsDVzC5aq0LsIc/copy) 168 | [Click here to make a copy of the extensions test doc file](https://docs.google.com/document/d/1_v0gAswpNnGnDqAx7cU_1bFEK8J7fi8EBvfKvgGZubc/copy) 169 | 170 | Once you have both files, you'll need to get their IDs and set the correct environment variables so the test runner finds them. To get the IDs **look at the URLs of the files** in your browser - it is the long string of random characters and numbers near the end. 171 | 172 | https://docs.google.com/document/d/**1coln1etP5rT1MqmNtRT7lToGtCi1EAsDVzC5aq0LsIc**/edit 173 | 174 | Set the following environmental variables in your shell: 175 | 176 | ```sh 177 | export BASIC_DOCUMENT_ID= 178 | export EXTENSIONS_DOCUMENT_ID= 179 | ``` 180 | 181 | Next you'll need to create a service account (or use an existing one) and give it access to your two copies of the docs. Typically this is done by sharing those files with the email of the service account in the document sharing interface. 182 | 183 | Finally, we need to tell the test runner how to use the service account authentication to communicate with the API. The best method for doing this is the [service-to-service authentication method](https://github.com/googleapis/google-api-nodejs-client#service-to-service-authentication). Typically this means setting the `GOOGLE_APPLICATION_CREDENTIALS` environmental variable and pointing it at the location of your service account authentication JSON file. 184 | 185 | ```sh 186 | export GOOGLE_APPLICATION_CREDENTIALS= 187 | ``` 188 | 189 | And... now you're ready to go! You should be able to run the tests. 190 | 191 | ```sh 192 | yarn test 193 | ``` 194 | 195 | If anyone has any suggestions on how to make this a smoother process, please let me know! 196 | 197 | ## License 198 | 199 | MIT 200 | --------------------------------------------------------------------------------