zapier-platform-core

zapier-platform-core is the runtime SDK that every Zapier CLI integration installs as a dependency. It doesn’t scaffold your project or run standalone - instead it’s invoked behind the scenes on AWS Lambda every time a Zapier integration executes an action, trigger, or search, translating the raw event dispatched by Zapier’s monolith into the developer-facing bundle, input, and z object that integration code actually interacts with.

Maintained by Zapier as part of the zapier-platform monorepo alongside zapier-platform-cli and zapier-platform-schema, it ships a request client with built-in auth injection and request logging, a dehydration/hydration system for lazily resolving large payloads across invocation boundaries, and a middleware pipeline that wraps every perform function with consistent error handling, response caching, and schema validation. Integration authors rarely require() it directly - instead they build against its exported createAppTester and TypeScript types while the CLI and the platform runtime handle the rest.

What You Get

• A createAppHandler/createLambdaHandler entry point that wraps a schema-validated app definition into an AWS Lambda-ready function
• The z object (z.request, z.dehydrate, z.cursor, z.JSON, z.console) that every perform/trigger function receives at runtime
• An instrumented HTTP request client with automatic auth-header injection, request/response logging, and configurable before/after middleware
• createAppTester for writing and running local unit tests against your integration exactly as Lambda would invoke it
• Full TypeScript type definitions (types/*.d.ts), validated against real usage via tsd type tests

Common Use Cases

• Declaring authentication, triggers, searches, and actions for a Zapier CLI integration that zapier-platform-cli scaffolds and deploys
• Writing local unit tests for perform functions with createAppTester before pushing an integration to Zapier
• Handling large API responses or file payloads that exceed Lambda’s payload limits via z.dehydrate and the file-stasher tools
• Migrating a Legacy Web Builder integration onto the modern platform, paired with zapier-platform-legacy-scripting-runner

Under The Hood

Architecture The package’s job is to bridge Zapier’s monolith and developer code: the monolith’s call_into_js method sends an event directly to AWS Lambda, and createLambdaHandler (src/tools/create-lambda-handler.js) is the exact function signature that event invokes. Inside a Node Domain (a deprecated API the package still relies on for cross-cutting error capture), create-app.js composes a before/after middleware chain - fetchStashedBundle, addAppContext, and injectZObject run before a command executes, while checkOutput, largeResponseCachePointer, waitForPromises, and callbackStatusCatcher run after - around a command handler that dispatches schema-validated “execute” and “validate” commands. The z object handed to every perform function is assembled here too, with each of its members (z.request, z.dehydrate, z.cursor, and friends) implemented as its own file under src/tools.

Tech Stack The package is plain CommonJS JavaScript with hand-authored TypeScript declarations (types/*.d.ts) rather than a TypeScript source, published alongside an ESM entry point (index.mjs). Runtime dependencies include lodash, form-data, node-fetch@2, semver, dotenv, fernet for token encryption, and a workspace dependency on zapier-platform-schema for structural validation. It lives inside a pnpm-workspace monorepo (zapier/zapier-platform) built and linted with a shared root ESLint flat config, Prettier, and husky/lint-staged pre-commit hooks, with GitHub Actions CI running tests across every package.

Code Quality The core package carries 51 test files under test/ against 99 files under src/, using Mocha and the should assertion library, with nock for HTTP interception and mock-fs/dicer for filesystem and multipart edge cases. A separate solo-test script isolates a patch-opt-out scenario that can’t safely run inside the main suite, and a battery of *.test-d.ts files under types/ exercise the hand-written type declarations with tsd - an unusual and rigorous check for a package that ships JS rather than TypeScript source. Error handling is deliberately contextual: middleware.js’s enrichErrorMessages appends a “what happened” trace to thrown errors before they reach the developer. The validate script chains test, smoke-test, and lint together as a single release gate.

API Design Most integration authors never require() this package directly - they build against z, bundle, and createAppTester while zapier-platform-cli and the hosted platform handle wiring. That indirection keeps the public surface small and consistent (createAppHandler, createAppTester, a stable z object), but it also means getting started requires the companion CLI and external docs.zapier.com/platform documentation rather than anything in this package’s own README, which is aimed at contributors rather than integration authors.