@anvilco/anvil

Anvil API Client for Node

Anvil is a suite of tools for managing document-based workflows:

1. Anvil Workflows converts your PDF forms into simple, intuitive websites that fill the PDFs and gather signatures for you.
2. Anvil PDF Filling API allows you to fill any PDF with JSON data.

Currently, this node client only supports our PDF filling API.

Usage

yarn add @anvilco/anvil

npm install @anvilco/anvil

A basic example converting your JSON to a filled PDF, then saving the PDF to a file:

import fs from 'fs'
import Anvil from '@anvilco/anvil'

// The ID of the PDF template to fill
const pdfTemplateID = 'kA6Da9CuGqUtc6QiBDRR'
// Your API key from your Anvil organization settings
const apiKey = '7j2JuUWmN4fGjBxsCltWaybHOEy3UEtt'

// JSON data to fill the PDF
const exampleData = {
  "title": "My PDF Title",
  "fontSize": 10,
  "textColor": "#CC0000",
  "data": {
    "someFieldId": "Hello World!"
  }
}
const anvilClient = new Anvil({ apiKey })
const { statusCode, data } = await anvilClient.fillPDF(pdfTemplateID, exampleData)

console.log(statusCode) // => 200

// Data will be the filled PDF raw bytes
fs.writeFileSync('output.pdf', data, { encoding: null })

API

Instance Methods

new Anvil(options)

Creates an Anvil client instance.

• options (Object) - Options for the Anvil Client instance.

const anvilClient = new Anvil({ apiKey: 'abc123' })

fillPDF(pdfTemplateID, payload[, options])

Fills a PDF with your JSON data.

First, you will need to have uploaded a PDF to Anvil. You can find the PDF template's id on the API Info tab of your PDF template's page:

An example:

const pdfTemplateID = 'kA6Da9CuGqUtc6QiBDRR'
// Your API key from your Anvil organization settings
const apiKey = '7j2JuUWmN4fGjBxsCltWaybHOEy3UEtt'

// JSON data to fill the PDF
const payload = {
  "title": "My PDF Title",
  "fontSize": 10,
  "textColor": "#CC0000",
  "data": {
    "someFieldId": "Hello World!"
  }
}
// The 'options' parameter is optional
const options = {
  "dataType": "buffer"
}
const anvilClient = new Anvil({ apiKey })
const { statusCode, data } = await anvilClient.fillPDF(pdfTemplateID, payload, options)

• pdfTemplateID (String) - The id of your PDF template from the Anvil UI
• payload (Object) - The JSON data that will fill the PDF template
  • title (String) - optional Set the title encoded into the PDF document
  • fontSize (Number) - optional Set the fontSize of all filled text. Default is 10.
  • color (String) - optional Set the text color of all filled text. Default is dark blue.
  • data (Object) - The data to fill the PDF. The keys in this object will correspond to a field's ID in the PDF. These field IDs and their types are available on the API Info tab on your PDF template's page in the Anvil dashboard.
    • For example { "someFieldId": "Hello World!" }
• options (Object) - optional Any additional options for the request
  • dataType (Enum[String]) - optional Set the type of the data value that is returned in the resolved Promise. Defaults to 'buffer', but 'stream' is also supported.
• Returns a Promise that resolves to an Object
  • statusCode (Number) - the HTTP status code; 200 is success
  • data (Buffer | Stream) - The raw binary data of the filled PDF if success. Will be either a Buffer or a Stream, depending on dataType option supplied to the request.
  • errors (Array of Objects) - Will be present if status >= 400. See Errors
    • message (String)

createEtchPacket(options)

Creates an Etch Packet and optionally sends it to the first signer.

• options (Object) - An object with the following structure:
  • variables (Object) - See the API Documentation area for details. See Examples area for examples.
  • responseQuery (String) - optional A GraphQL Query compliant query to use for the data desired in the mutation response. Can be left out to use default.
  • mutation (String) - optional If you'd like complete control of the GraphQL mutation, you can pass in a GraphQL Mutation compliant string that will be used in the mutation call. This string should also include your response query, as the responseQuery param is ignored if mutation is passed. Example:

      mutation CreateEtchPacket (
        $name: String,
        ...
      ) {
        createEtchPacket (
          name: $name,
          ...
        ) {
          id
          eid
          ...
        }
      }
    

generateEtchSignUrl(options)

Generates an Etch sign URL for an Etch Packet signer. The Etch Packet and its signers must have already been created.

• options (Object) - An object with the following structure:
  • variables (Object) - Requires clientUserId and signerEid
    • clientUserId (String) - your user eid
    • signerEid (String) - the eid of the Etch Packet signer, found in the response of the createEtchPacket instance method

Class Methods

prepareGraphQLFile(pathOrStreamLikeThing[, options])

A nice helper to prepare a Stream-backed or Buffer-backed file upload for use with our GraphQL API.

• pathOrStreamLikeThing (String | Stream | Buffer) - An existing Stream, Buffer or other Stream-like thing supported by FormData.append OR a string representing a fully resolved path to a file to be read into a new Stream.
• options (Object) - Anything supported by FormData.append. Likely required when providing a non-common stream. From the form-data docs:

  Form-Data can recognize and fetch all the required information from common types of streams (fs.readStream, http.response and mikeal's request), for some other types of streams you'd need to provide "file"-related information manually

• Returns an Object that is properly formatted to be coerced by the client for use against our GraphQL API wherever an Upload type is required.

Types

Options

Options for the Anvil Client. Defaults are shown after each option key.

{
  apiKey: <your_api_key> // Required. Your API key from your Anvil organization settings
}

Rate Limits

Our API has request rate limits in place. This API client handles 429 Too Many Requests errors by waiting until it can retry again, then retrying the request. The client attempts to avoid 429 errors by throttling requests after the number of requests within the specified time period has been reached.

See the Anvil API docs for more information on the specifics of the rate limits.

API Documentation

Our general API Documentation can be found here. It's the best resource for up-to-date information about our API and its capabilities.

See the PDF filling API docs for more information about the fillPDF method.

Examples

Check out the example folder for running usage examples!

Development

First install the dependencies

yarn install

Running tests

yarn test
yarn test:watch

Building with babel will output in the /lib directory.

yarn test

# Watches the `src` and `test` directories
yarn test:watch

Changelog

v2.2.0 - 2020-09-29

Merged

• Cut new version: v2.2.0 #25
• Add aliasId AND routingOrder to createEtchPacket mutation query response default #24
• rename send to draft (and flip the logic) in createEtchPacket #23
• no organizationEid allowed when calling via API key #22
• change fillPayload param to just data #21
• Fix file upload related stuff to reflect reality #20
• Etch API Support for Embedded Signers #18
• Bump node-fetch from 2.6.0 to 2.6.1 #19
• Add support for GraphQL API, starting with createEtchPacket #16
• v2.1.0 #14
• replace request with node-fetch #13
• Bump lodash from 4.17.15 to 4.17.19 #12
• Add back in the dirName and add ability to autogen CHANGELOG #11
• Use module.exports instead of import/export #10
• Target node 8; remove regeneratorRuntime dependency #5
• Dependencies update to mitigate security vulnerability #9
• Bump acorn from 7.1.0 to 7.1.1 #8

Commits

• don't need babel anymore 2b9daad
• dependency upgrades: nodemon, mocha, and yargs due to dot-prop and yargs-parser vulnerabilities c118d23
• bump deps to get minimist to >= 1.2.2 26e4cd1