Commentary Forms SDK

Browser SDK for Commentary custom form renderers.

The SDK lets customer-owned interactive form experiences submit structured values back to Commentary through the existing review iframe session. It is designed to run only inside a Commentary review iframe that has completed nonce-bound session initialization.

Framework Compatibility

The SDK does not depend on React, Next.js, Vue, Svelte, Angular, Astro, Vite, or any other frontend framework. It requires a real browser window with iframe embedding and postMessage.

Install

npm install @commentary-dev/forms-sdk

For CDN usage, load the browser bundle:

<script src="https://cdn.commentary.dev/forms-sdk/latest/commentary-forms-sdk.js"></script>

Usage

Configure the Commentary parent origin before the script when your review shell does not run at the default Commentary origin:

<script>
  window.__COMMENTARY_PARENT_ORIGIN__ = "https://commentary.dev";
  window.__COMMENTARY_PARENT_ORIGINS__ = ["https://commentary.dev", "https://staging.commentary.dev"];
</script>
<script src="https://cdn.commentary.dev/forms-sdk/latest/commentary-forms-sdk.js"></script>

Submit structured values after the review iframe session initializes:

await window.CommentaryForms.submitForm({
  formId: "customer-intake",
  formVersionHash: "fnv1a32:...",
  status: "final",
  values: {
    name: "Ada",
    email: "[email protected]"
  },
  rendererMetadata: {
    name: "checkout-custom-form",
    mode: "interactive_experience"
  }
});

Commentary validates final values against the Form Contract and returns machine-readable diagnostics when the values are invalid. The SDK does not ask Commentary to fetch renderer URLs or run renderer JavaScript.

Package Outputs

• dist/commentary-forms-sdk.js: self-initializing browser SDK.
• dist/index.d.ts: ambient browser configuration declarations.

Release

This package is published as @commentary-dev/forms-sdk and mirrored to https://cdn.commentary.dev/forms-sdk/.