Zapier Platform

The zapier-platform CLI is the primary tool for building Zapier integrations. As of version 19, the CLI exposes only the zapier-platform command. Note that the legacy zapier binary has been removed and should no longer be used.

For detailed command usage and schema definitions, refer to the official documentation links provided in the CLI package.

The zapier-platform-cli (invoked via the zapier-platform command) is the primary tool for developers to build and manage integrations on the Zapier platform. It is available on npm as zapier-platform-cli.

Key operational details:

• The CLI is used to perform all operations required for integration development.
• The core, schema, and cli packages are released in synchronized version numbers to ensure compatibility.

# Install via npm
npm install -g zapier-platform-cli

The zapier-platform-legacy-scripting-runner is a compatibility shim designed to bridge the gap between the legacy v2 platform and the current v3 (CLI) platform. It is primarily used when auto-converting legacy applications to the modern platform to ensure they continue to function correctly.

It implements the full suite of features found in the legacy scripting environment, including global functions and specific libraries that were standard in the v2 environment.

The zapier-platform-core package acts as the runtime bridge between the Zapier monolith and your developer code. While you may import it for TypeScript types and testing, it is not directly required in your application code. Instead, it runs your app's exposed functions at runtime.

Its primary responsibilities include:

• Organizing data passed from the Zapier monolith into your code.
• Maintaining the z object, which provides essential utility functions.
• Managing command execution (like execute and validate) for compiled apps.

Note: The core, schema, and cli packages are always released together under matching version numbers.

The Zapier CLI is powered by oclif. Commands follow a standard pattern where top-level commands and sub-commands are organized into specific files.

Examples of command patterns:

• Top-level commands: zapier-platform push, zapier-platform test.
• Sub-commands: zapier-platform env:get (using colon notation for namespaces).

All commands inherit from ZapierBaseCommand, which provides built-in methods for:

• Parsing flags
• Printing structured data
• Verifying authentication

The zapier-platform-schema package serves as the single source of truth for validating the structure of Zapier apps.

• Key Output: It produces an exported-schema.json file.
• Usage: This JSON schema is consumed by other packages (like core and cli) to ensure that app definitions, triggers, and actions conform to the platform's requirements.
• Independence: It is a standalone package that does not depend on other platform packages.

Starting with version 10, Zapier automatically parses JSON and form-encoded response bodies.

• Use response.data to access the parsed object.
• response.json is still available for JSON bodies but is less preferred.
• Breaking Change for afterResponse: If you have an afterResponse hook that modifies response.content expecting shorthand requests to pick up the change, you must switch to assigning the parsed/transformed object to response.data instead (e.g., response.data = parsedOrTransformed).

The runner provides several critical mechanisms to maintain backward compatibility:

• Global Function Availability: It uses compileLegacyScriptingSource to make the global functions that were standard in the legacy environment available to scripts.
• Lifecycle Hook Management: It handles pre_X and post_X lifecycle hooks via the runEventCombo function.
• Input/Output Compatibility: It ensures that inputs and outputs remain compatible with legacy requirements, even if the modern CLI platform has stricter requirements (e.g., requiring triggers to return arrays).
• Legacy Libraries: It provides individual implementations for legacy-specific utilities, such as btoa and $ (for jQuery).

The legacy pattern for dynamic dropdowns (also known as dynamic choices) uses a separate trigger to fetch the available choices. You reference the trigger using the dynamic property in your field definition.

Format: "triggerKey.idField.labelField"

In this format, Zapier uses the idField as the underlying value and the labelField as the display text for the user.

{
  key: 'species_id',
  type: 'integer',
  label: 'Species',
  dynamic: 'species.id.name',  // Format: "triggerKey.idField.labelField"
}