@cargo-ai/form-sdk

Zero-dependency browser SDK for embedding Cargo public forms. It loads a Tool's deployed form schema, renders it (or runs headless), and submits to the public Cargo Form API which executes the Tool's workflow.

Embed (CDN)

The CDN bundle loads with async, so the snippet starts with a stub that queues Cargo.loadForm calls made before the bundle finishes loading; the bundle drains the queue (and resolves the returned promises) on load.

<div data-cargo-form="TOOL_UUID"></div>
<script>
  window.Cargo = window.Cargo || {};
  Cargo.loadForm =
    Cargo.loadForm ||
    function () {
      var call = { args: arguments };
      call.promise = new Promise(function (resolve, reject) {
        call.resolve = resolve;
        call.reject = reject;
      });
      (Cargo._q = Cargo._q || []).push(call);
      return call.promise;
    };

  Cargo.loadForm("TOOL_UUID", { mode: "sync" }, (form) => {
    form.addHiddenFields({ page_url: location.href });
    form.onSuccess((values, response) => {
      location.href = "/thank-you";
      return false;
    });
  });
</script>
<script src="https://cdn.getcargo.io/forms/v1.js" async></script>

npm

import { loadForm } from "@cargo-ai/form-sdk";

const form = await loadForm("TOOL_UUID", {
  render: "headless", // or "render" (default)
  mode: "async", // or "sync" (default)
});

form.setValues({ email: "[email protected]" });
await form.submit();

Options

• baseUrl — Cargo API base URL (default https://api.getcargo.io).
• render — "render" builds the form DOM from the schema; "headless" does not.
• mode — "sync" waits for and returns run output; "async" returns immediately and polls.
• pollTimeoutMs — in "async" mode, how long to poll before onSuccess gets a pending response (default 60000). The run keeps going server-side.
• target — element or selector to render into (defaults to [data-cargo-form]).
• autoCaptureUtm — capture UTM params + page URL automatically (default true).

Lifecycle

setValues, addHiddenFields, getValues, onValidate, onSubmit, onSuccess, onError, submit.

Privacy & anti-spam

• Respects Global Privacy Control / Do Not Track: when opted out, no anonymous id or UTM capture happens.
• Injects a honeypot field and a render timestamp (time-trap) consumed by the server-side spam guards. When a CAPTCHA provider is configured for the form, pass the token via form.addHiddenFields({ [CAPTCHA_TOKEN_FIELD]: token }).

Build

• npm run build — ESM npm artifact (build/src/index.js).
• npm run build:cdn — minified IIFE CDN bundle exposing window.Cargo.