zapier-platform-core

zapier-platform-core Docs

This is the documentation for the core of Zapier.

---

• Getting Started
  • Installing the CLI
  • Customizing your App
• Calling Methods (perform, inputFields, etc.)
• Inside Methods
  • z object
    • z.request()
    • z.JSON.stringify()
    • z.JSON.parse()
    • z.hash()
    • z.console.log()
    • z.console.info()
    • z.console.warn()
    • z.console.error()
    • z.console.trace()
    • z.dehydrate()
    • z.dehydrateRequest()
    • z.dehydrateFile()
  • bundle object
• Authentication
• Input Data
• Output Data
• Environment

---

Getting Started

The Zapier platform is a Node based environment with a corresponding CLI that makes developer mature, tested integrations a breeze.

Installing the CLI

$ npm install -g zapier-platform-cli
$ zapier auth
$ zapier create "Hello World" --helloworld

Customizing your App

The simplest way to customize your app are:

• Use the zapier scaffold commands
• Write everything yourself
• Use some meta tools like zapier.createTrigger() to build (TODO)

Calling Methods (perform, inputFields, etc.)

When you define an app definition, we will find your registered functions and those are what we'll call in the platform. For example, a very slimmed down app definition might look like this:

const App = {
  triggers: {
    contactList: {
      operation: {

        inputFields: [
          {key: 'greeting'}, // static fields!
          (z, bundle) => [{key: 'name'}], // dynamic!
        ]
        perform: (z, bundle) => {
          // let's just return something silly here :-D
          const phrase = `${bundle.inputData.greeting} ${bundle.inputData.name}`;
          return [{id: 123, phrase}];
        }

      }
    }
  }
};

Behind the scenes our system is designed to resolve inputFields to show to the user as a form, and then pass those into the perform call as bundle.inputData. If you need to perform async, you should return a Promise.

Learn more about the app definition by reading our Schema!

Inside Methods

Every method call will get two arguments: z and bundle.

z object

We provide several methods off of the z object, which is provided as the first argument in all function calls in your app.

z.request()

• accepts z.request([url], requestOptions) goto
• returns Promise wrapped response goto

A pre-configured client from createAppRequestClient() built on node-fetch.

// provide a plain string
const url = 'http://httpbin.org/get';
z.request(url)
  .then(response => {
    z.console.log(response.status, response.content);
  });

// or provide an object of requestOptions
const requestOptions = {
  url: 'http://httpbin.org/get',
  params: {hello: 'world'}, // querystring
  headers: {'Accept': 'application/json'},
  timeout: 5000
};
z.request(requestOptions)
  .then(response => {
    z.console.log(response.status, response.content);
  });

requestOptions

• method - default 'GET' (see node-fetch docs)
• params - an object of querystring options (like querystring)
• body - a string or object/array for JSON
• headers - an object of headers (see node-fetch docs)
• merge - default true, merges this request into any requestTemplates you provide in your app
• replace - default true, renders the bundle into the request, IE: '{{inputData.name}}' -> 'bryan'
• redirect - default 'follow' (see node-fetch docs)
• follow - default 20, max redirects (see node-fetch docs)
• compress - default true (see node-fetch docs)
• agent - default null, http.Agent instance (see node-fetch docs)
• timeout - default 0/disabled, max wait in ms (see node-fetch docs)
• size - default 0/disabled, max response bytes size (see node-fetch docs)

response

Note! This is wrapped in a Promise!

• status - a status code, like 200
• content - raw decoded body string, like '{"hello":"world"}'
• request - the original options passed into
• headers - raw headers object
• getHeader - case insensitive lookup for headers

z.JSON.stringify()

A wrapper of JSON.stringify() that gives slightly nicer error messages.

z.JSON.parse()

A wrapper of JSON.parse() that gives slightly nicer error messages.

z.hash()

A simple interface to many of the standard crypto routines node provides, for example:

const hashedPassword = z.hash('sha256', 'my password');

z.console.log()

Similar to native console.log() but logged to our distributed logger, viewable by zapier logs --console command.

z.console.info()

Similar to native console.info() but logged to our distributed logger, viewable by zapier logs --console command.

z.console.warn()

Similar to native console.warn() but logged to our distributed logger, viewable by zapier logs --console command.

z.console.error()

Similar to native console.error() but logged to our distributed logger, viewable by zapier logs --console command.

z.console.trace()

Similar to native console.trace() but logged to our distributed logger, viewable by zapier logs --console command.

z.dehydrate()

• accepts z.dehydrate(methodPathOrFunc, [inputData])
• returns String pointer

Dehydration as a concept is what we call "lazy object resolution". For example, your app may have hundreds of related objects available under different API endpoints. It could be useful to provide those related objects, but it is wasteful to eagerly grab them. Dehydrate creates a pointer that helps us

methodPathOrFunc

Can be one of the following:

• 'models.contact.get.operation.perform' an already full path
• 'contact.get' shorthand which will expand into a model full path
• 'contact_list' shorthand which will expand into a hydrator/trigger/search/write full path
• 'trigger.contact_list' shorthand which will expand into trigger full path
• Function a direct reference to a function that can be found in your app's definition

We will raise a descriptive error if we can't resolve the methodPathOrFunc.

inputData

Any object you'd like to provide to your function.

z.dehydrateRequest()

• accepts z.dehydrateRequest(requestOptions) goto
• returns String pointer

z.dehydrateFile()

TODO.

bundle object

This payload will provide user provided data and configuration data.

• authData - user provided authentication data, like api_key or even access_token if you are using oauth2 [(read more on authentication)[#authentication]]
• inputData - user provided configuration data, like listId or tagSlug as defined by inputData [(read more on input data)[#inputdata]]
• environment - environment variables from process.env or from CLI config zapier env (usually app secrets) [(read more on environment)[#environment]]

Authentication

TODO!

Input Data

TODO!

Output Data

TODO!

Environment

TODO!