Zvid custom app for Make

Source bundle for the Zvid custom app on Make: render videos and images from JSON or reusable templates, use Zvid's creative and stock libraries, and react to render events with an instant trigger.

The operation surface matches the current Zvid n8n node. The bundle also includes the universal module, pagination, static interfaces, samples, error classification, and test evidence plan required for Make app review.

Included components

Group	Modules
Renders	Create a render, bulk create renders, validate a render payload, get a render, get a bulk render, search renders, watch render events
Templates	List, get, create, update, archive, duplicate, preview, and render from templates
AI Authoring	Plan a creative video, get the project schema, list supported elements, get element documentation, get an example project, repair project JSON
Creative Library	Search assets, get asset metadata, get complete asset content
Stock Library	Get media-type availability and search Zvid's stock library
Account	Get the credit balance and make an authorized API call

The API-key connection validates against GET /api/user/profile. Shared requests use https://api.zvid.io, send the x-api-key header, sanitize that header in Make logs, and classify authentication, insufficient-credit, and rate-limit errors.

What can and cannot run locally

Unlike an n8n community node, a Make custom-app module cannot be executed by Node.js or Docker on your computer. Make's IML runtime is hosted by Make. The official local workspace is an editor and source-control workflow; after deployment, the actual module is tested in Make Scenario Builder.

Make's local IML tests test custom JavaScript IML functions; they do not execute a module's HTTP communication. This app uses built-in IML functions only. Get a bulk render parses each job's dates with iterate and uses wrapper to preserve one batch bundle containing the jobs array. Custom-function permissions are not required.

Use these three test layers:

1. npm.cmd test checks the Make source locally without making network calls.
2. npm.cmd run test:production sends the same HTTP requests from this computer to the production Zvid API. This checks the production key and API contracts, but not Make's IML evaluation.
3. A private Zvid Local app in Make is the only place to execute and inspect the actual Make module. This does not publish the app or submit it for review.

1. Offline source test

cd D:\Nodejs\Projects\zvid-cline\zvid-integrations\make-app
npm.cmd test

The validator parses every IML file and checks module/catalog parity, interfaces and samples, search limits and pagination, canonical URLs, credential sanitization, universal-module URL safety, n8n operation parity, public stock-library copy, and fail-closed webhook verification.

For expression-level regression tests, set MAKE_IML_PATH to the node_modules/@integromat/iml directory bundled with the official Make Apps Editor extension, then run npm.cmd run test:iml. These tests execute Make's actual hash, conversion, and date functions. Hosted webhook delivery, response wrapping, and HTTP error handling also require scenario tests.

2. Local process against the production API

Keep the production key out of shell history by entering it as a masked value:

$zvidSecureKey = Read-Host "Zvid API key" -AsSecureString
$env:ZVID_API_KEY = [System.Net.NetworkCredential]::new("", $zvidSecureKey).Password
npm.cmd run test:production

This authenticates, exercises free/read-only endpoints, gets a production example project, and validates it. It does not submit a render or spend render credits. The script prints only check names and statuses, never the key or complete API responses.

To validate your own project JSON:

npm.cmd run test:production -- --project "C:\path\to\project.json"

To explicitly submit that project to production, wait for completion, and spend credits:

npm.cmd run test:production -- --project "C:\path\to\project.json" --render

Omit --project to use Zvid's small built-in still-image example. --render is deliberately opt-in.

Remove the key from the current shell when testing is finished:

Remove-Item Env:ZVID_API_KEY

3. Execute the actual module in Make

The folder passed to npm.cmd run scaffold:clone is not a runnable local app. It is a workspace generated by the official Make Apps Editor and linked to your private Make app. Scaffolding creates or updates the local component definitions and copies this repository's IML into that workspace; deployment uploads it to Make for execution.

For the quickest first execution, follow the web-editor walkthrough in submission/LOCAL_TEST.md. It starts with one read-only module, then validates and submits a small production image render. No clone is required for that first test.

1. In Make, create an unpublished private custom app named Zvid Local. Add one API Key connection labeled Zvid API key. Install the official Make Apps Editor VS Code extension and sign in.

2. In VS Code, run Make Apps Editor: Clone app and choose Zvid Local. Pick any scratch folder outside this repository, for example C:\make-apps\zvid-local. That chosen folder is the <private-clone-folder> below.

3. From this repository, preview and then build the complete local clone:

   npm.cmd run scaffold:clone -- "C:\make-apps\zvid-local"
   npm.cmd run scaffold:clone -- "C:\make-apps\zvid-local" --write

   The first command is a dry run. The second creates all 28 local module definitions, the render-event webhook, groups, and mapped IML files. It preserves existing Make origin mappings and never reads or changes .secrets.

4. Reload the VS Code window so the extension sees the generated files. Right-click the clone's makecomapp.json, select Deploy to Make, and select the private Zvid Local origin. Confirm creation of the previously unmapped local components when prompted.

5. In Make Scenario Builder, create a scenario and add Zvid Local > Get the credit balance. Create a connection with a production key from https://app.zvid.io/api-keys, select Run this module only, and inspect its input/output bundles.

6. Add Get an example project with Still image, map its example.payload into Validate a render payload, and run. Then map the validated payload into Create a render, select image, and run it when you are ready to spend credits.

7. Run the complete review coverage in submission/TEST_PLAN.md before cloud submission.

After the structure has been deployed once, use npm.cmd run sync -- "<private-clone-folder>" --write for source-only refreshes that must not change makecomapp.json.

Make's own guide likewise tests a private-tagged custom app by adding it to a scenario and choosing Run once. See Test your app.

The source files map directly to the Make editor tabs:

• general/base.iml.json -> Base
• connections/zvid-api-key/ -> connection Parameters and Communication
• modules/<name>/ -> module Communication, Mappable parameters, Interface, and Samples
• webhooks/render-events/ -> webhook Attach, Detach, and Communication

If a module already exists in the private app, update it in place. Internal component names become compatibility identifiers after publication, and Make does not allow public components to be removed casually.

Validate-before-render pattern

For AI-generated projects, retrieve the schema, a close creative-library example, and the relevant element documentation before composing JSON. Treat validation errors and layout warnings as fix-before-render feedback.

For mapped or generated project JSON, insert Validate a render payload before Create a render:

• valid = true → render; creditsRequired shows the expected cost and payload contains the resolved project.
• Invalid payload → the API returns HTTP 400 and Make raises a validation error with its message and available field details. Add an error-handler route to send that feedback to the authoring step or an error notification.

Make's response.valid directive does not convert HTTP 400 into a successful bundle. Validation runs the same backend resolution and plan-aware schema pipeline as render submission without enqueueing work or spending credits. For additional authoring guidance, see the zvid-schema package and the @zvid/mcp server; backend validation remains the source of truth.

Webhook verification

Creating the attached webhook registers its URL with Zvid; deleting it invokes the detach procedure. Enable the scenario to process events immediately. Zvid signs deliveries as sha256=hex(hmac(secret, "<timestamp>.<raw body>")) in X-Zvid-Signature, with the timestamp in X-Zvid-Timestamp.

The signature check hashes toString(rawBody) so Make's binary request buffer is decoded as UTF-8 before concatenating the timestamp. Hosted EU1 tests confirmed raw-body availability, successful signed test and render events, and HTTP 401 rejection for missing or forged signatures. No JSON re-serialization is used.

The signing secret saved by the attach response is available as data.secret. The check requires a nonempty secret, timestamp, signature, and raw body. Invalid requests are handled by verification.respond with HTTP 401. A top-level false condition bypasses the response configuration and returns Make's default HTTP 200, so it must not be used to reject signatures. Make's public IML function takes text, output encoding, key; its internal crypto helper uses a different order. Passing the secret as the second IML argument computes an unsigned hash and must not be used. Runtime tests cover strings, binary buffers, noncanonical JSON, missing values, and tampered bytes.

Verify a real completed/failed delivery and a rejected invalid-signature delivery in the private app before review. The webhook component owns the connection; the instant trigger references that webhook.

Cloud submission handoff

The repository portion is review-oriented, but final submission requires platform-side evidence and metadata:

1. Complete every private scenario in submission/TEST_PLAN.md, including the retained error and pagination logs.
2. Remove disposable test connections or components. Keep only the components intended for the public app.
3. Confirm visible module labels/descriptions match submission/module-catalog.json, upload the production icon, and link the public API documentation at https://docs.zvid.io.
4. Use https://zvid.io as the service URL and https://zvid.io/contact as the support contact.
5. Publish the custom app, make the intended modules visible, and submit the Make review form with the fresh test-scenario links.

Publishing and requesting review are intentionally not performed from this repository. Make makes publication irreversible and requires the owner to provide current scenario logs and organization-specific review details.

Community and support

Join the Zvid community on Discord to ask questions, discuss video automation workflows, and share what you build. For private account or billing questions, contact us at https://zvid.io/contact.