@newswire/doc-to-archieml is a simple wrapper around the Google Docs API and ArchieML for converting the contents of a Google Doc into a ArchieML-produced data structure.
- ⚙️ Produces identical output to ArchieML's example Google Drive export method (including support for converting links to
<a>tags) without the use of an HTML parser - 👩🔧 Does not expect any particular method of authenticating with Google — use the authenticated Google API instance, Google Docs client or authentication method you are already using
@newswire/doc-to-archieml requires a version of Node.js 8 or higher. It is available via npm.
npm install --save-dev @newswire/doc-to-archieml
# or
yarn add --dev @newswire/doc-to-archieml@newswire/doc-to-archieml exports a single function - docToArchieML.
const { docToArchieML } = require('@newswire/doc-to-archieml');
const { google } = require('googleapis');
async function main() {
// this method looks for the GCLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS
// environment variables to establish authentication
const auth = await google.auth.getClient({
scopes: ['https://www.googleapis.com/auth/documents.readonly'],
});
// pass in the valid authentication and ID of the document you want to process
const results = await docToArchieML({ documentId: '...', auth });
console.log(results); // `results` is your ArchieML-produced JavaScript object
}
main().catch(console.error);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.
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 and the client library's authentication documentation.
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.
After establishing authentication using one of the methods supported by googleapis, you can pass this auth directly to docToArchieML and it'll handle the rest.
const { docToArchieML } = require('@newswire/doc-to-archieml');
const { google } = require('googleapis');
async function main() {
// this method looks for the GCLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS
// environment variables to establish authentication
const auth = await google.auth.getClient({
scopes: ['https://www.googleapis.com/auth/documents.readonly'],
});
// pass in the valid authentication, which is used to create a Google Docs API client internally
const results = await docToArchieML({ documentId: '...', auth });
}
main().catch(console.error);(This example uses the service-to-service authentication method.)
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!
const { docToArchieML } = require('@newswire/doc-to-archieml');
const { google } = require('googleapis');
async function main() {
// this method looks for the GCLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS
// environment variables to establish authentication
const auth = await google.auth.getClient({
scopes: ['https://www.googleapis.com/auth/documents.readonly'],
});
// create your own Google Docs API client
const client = google.docs({
version: 'v1',
auth,
});
// pass in the authenticated Google Docs API client
const results = await docToArchieML({ documentId: '...', client });
}
main().catch(console.error);(This example uses the service-to-service authentication method.)
Maybe you've been using multiple Google API services and have set authentication across all Google APIs globally. docToArchieML can accept the authenticated googleApisInstance and use that to create the Google Docs API client - no passing of auth necessary.
const { docToArchieML } = require('@newswire/doc-to-archieml');
const { google } = require('googleapis');
async function main() {
// this method looks for the GCLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS
// environment variables to establish authentication
const auth = await google.auth.getClient({
scopes: ['https://www.googleapis.com/auth/documents.readonly'],
});
// set auth as a global default
google.options({ auth });
// pass in the GoogleApisInstance, which will be used to connect to the Google Docs API
const results = await docToArchieML({ documentId: '...', google });
}
main().catch(console.error);(This example uses the service-to-service authentication method.)
First clone the repo to your local device and install the dependencies.
yarnAfter 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.
First make a copy of the two test doc files:
Click here to make a copy of the basic test doc file Click here to make a copy of the extensions test doc file
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.
https://docs.google.com/document/d/1coln1etP5rT1MqmNtRT7lToGtCi1EAsDVzC5aq0LsIc/edit
Set the following environmental variables in your shell:
export BASIC_DOCUMENT_ID=<basic_doc_id>
export EXTENSIONS_DOCUMENT_ID=<extensions_doc_id>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.
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. Typically this means setting the GOOGLE_APPLICATION_CREDENTIALS environmental variable and pointing it at the location of your service account authentication JSON file.
export GOOGLE_APPLICATION_CREDENTIALS=<path_to_json_file>And... now you're ready to go! You should be able to run the tests.
yarn testIf anyone has any suggestions on how to make this a smoother process, please let me know!
MIT