Zapier Integration — Publishing Guide

Repository

The Zapier integration lives in schemastack-zapier/ (separate repo from the main backend/frontend).

Local Development

cd schemastack-zapier
npm install
npm test          # runs Jest tests with nock HTTP mocks

Local .env file

Create a .env file for local testing (excluded from git):

SCHEMASTACK_BASE_URL=http://localhost:8083
authData_apiKey=sk_your_api_key_here
authData_orgSlug=your-org-slug
authData_workspaceSlug=your-workspace-slug

• SCHEMASTACK_BASE_URL — overrides the production base URL (https://data.schemastack.io) for local dev
• authData_* — auth fields automatically loaded by zapier-platform invoke (no --auth flag needed)

The API key is a workspace API key created in Admin Console → Workspace Settings → API Keys.

Invoke locally

With .env configured and the workspace-api running on localhost:8083:

zapier-platform invoke auth test                                       # verify connection
zapier-platform invoke trigger table_list                              # list tables
zapier-platform invoke trigger new_row --inputData '{"table":"customers"}'  # fetch rows
zapier-platform invoke create create_row --inputData '{"table":"customers","name":"Test"}'
zapier-platform invoke search find_row --inputData '{"table":"customers","search_field":"name","search_value":"Test"}'

Publishing to Zapier Marketplace

Prerequisites

npm install -g zapier-platform-cli
zapier-platform login      # opens browser to authenticate with your Zapier account

First-time setup

cd schemastack-zapier
zapier-platform register "SchemaStack"    # registers the app with Zapier

Deploy a version

zapier-platform validate                  # check app structure and config
npm test                                  # verify all tests pass
zapier-platform push                      # deploy to Zapier's servers
zapier-platform push --skip-dep-install   # faster rebuild (skips npm install)

Testing with real users

zapier-platform users:add user@example.com 1.0.0   # invite a specific user to test
zapier-platform team:add user@example.com           # add permanent team member

Promote to production

zapier-platform promote 1.0.0             # mark version as production-ready

Submit for marketplace review

Go to developer.zapier.com and:

1. Upload app icon (256x256 PNG, square, no transparency)
2. Write marketplace description and select category (Databases / Developer Tools)
3. Add test account credentials for Zapier's review team
4. Submit for review (typically 1–2 weeks)

Marketplace approval requirements

• Working test account Zapier reviewers can use
• At least 1 trigger + 1 action
• App icon and description
• All zapier-platform validate checks pass
• Error messages are user-friendly
• Dynamic fields load correctly for table/column selection

App Structure

schemastack-zapier/
├── index.js              # App definition, auth middleware, cleanInputData flag
├── authentication.js     # API key auth via /_meta endpoint
├── triggers/
│   ├── table_list.js     # Hidden — powers table dropdown in all triggers/actions
│   ├── new_row.js        # Polling: sort by id desc
│   └── updated_row.js    # Polling: sort by updated_at desc
├── creates/
│   ├── create_row.js     # POST new row with dynamic fields
│   └── update_row.js     # PUT existing row by ID with dynamic fields
├── searches/
│   └── find_row.js       # GET with filter[field]=value
├── resources/
│   ├── api.js            # Base URL, /_meta client for table listing + field loading
│   └── fields.js         # Dynamic field loading + DB type → Zapier type mapping
├── test/                 # Jest tests with nock HTTP mocks
├── .env                  # Local dev config (git-ignored)
└── .gitignore            # Excludes node_modules, .env, build/, .zapierapprc

API Endpoints Used

All requests go to https://data.schemastack.io (workspace-api service) in production, overridable via SCHEMASTACK_BASE_URL env var. Authenticated via Authorization: Bearer <api_key> header.

Endpoint	Used by	Purpose
GET /_meta	Auth test, table list, field mapping	Workspace metadata with entities + columns
GET /{table}	new_row, updated_row triggers	Query rows with sort/pagination
POST /{table}	create_row action	Create a new row
PUT /{table}/{id}	update_row action	Update existing row
GET /{table}?filter[field]=value	find_row search	Search by field value

How dynamic fields work

1. User selects a table from the dropdown (powered by table_list trigger → /_meta)
2. Zapier calls getFields() which fetches /_meta again and finds the matching entity
3. Column types are mapped: varchar → string, int → integer, boolean → boolean, timestamp → datetime, etc.
4. Length suffixes like varchar(255) are stripped before type lookup
5. Fields are presented to the user with labels from column displayName or name

Versioning

Bump version in package.json before each zapier-platform push. Users on older versions are not auto-migrated — use zapier-platform migrate to move users between versions.

zapier-platform migrate 1.0.0 1.1.0 100%    # migrate all users from 1.0.0 to 1.1.0

Monitoring

zapier-platform logs                        # view recent invocation logs
zapier-platform logs --type http            # view HTTP request/response logs
zapier-platform env:set 1.0.0 KEY=value     # set environment variables

Quick Deploy Checklist

# 1. Bump version in package.json
# 2. Test
npm test
zapier-platform validate
# 3. Deploy
zapier-platform push
# 4. Promote (when ready for production)
zapier-platform promote X.Y.Z

Troubleshooting

Problem	Cause	Fix
/_meta returns 401	API key not recognized	Verify key in Admin Console, check Authorization: Bearer header
Table dropdown empty	/_meta response shape mismatch	Check api.js → listTables() parsing
Fields not loading	Column type not in type map	Add type to fields.js → TYPE_MAP, check zapier-platform logs
Triggers return empty	Table has no data or sort column missing	Verify table has rows, updated_row requires updated_at column
ENOTFOUND data.schemastack.io	No network, or a typo in the host	Set SCHEMASTACK_BASE_URL=http://localhost:8083 in .env