@clickterm/widget

Browser SDK (TypeScript) that embeds Clickterm clickwrap agreements into host pages, either as a modal dialog or an inline checkbox.

Install

npm install @clickterm/widget

Or load it directly from a CDN (UMD build, exposes window.Clickterm):

<script src="https://unpkg.com/@clickterm/widget"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/@clickterm/widget"></script>

Quick start

Dialog (modal) — with a bundler

import { ClicktermClient, ClicktermDialog } from '@clickterm/widget';

ClicktermClient.initialize('YOUR_APP_ID');

const result = await ClicktermDialog.show(
  {
    endUserId: 'user_12345',
    clickwrapTemplateId: 'YOUR_TEMPLATE_ID',
  },
  {},
  {
    onSuccess: (signature) => console.log('signed:', signature),
    onAlreadyAccepted: () => console.log('already accepted'),
    onCancel: () => console.log('dismissed'),
    onError: (err) => console.error(err),
  },
);

Inline (checkbox in your own form) — via script tag

<div id="my-consent"></div>

<script src="https://unpkg.com/@clickterm/widget"></script>
<script>
  const { ClicktermClient, ClicktermDom } = window.Clickterm;

  ClicktermClient.initialize('YOUR_APP_ID');

  ClicktermDom.renderInline('my-consent', {
    endUserId: 'user_12345',
    clickwrapTemplateId: 'YOUR_TEMPLATE_ID',
  }).then((handle) => {
    document.getElementById('my-form').addEventListener('submit', async (e) => {
      e.preventDefault();
      const result = await handle.finalize();
      console.log(result.status, result.clicktermSignature);
    });
  });
</script>

See docs/inline-clickwrap.md for the full inline integration guide (styling, multiple clickwraps per page, template placeholders, edge cases).

Public API

All exports live on src/index.ts. Three static classes:

• ClicktermClient.initialize(appId, baseUrl?) — configures the SDK. Must be called first.
• ClicktermDialog.show(request, config?, listeners?) / showAcceptedContent(request, config?) — modal flow.
• ClicktermDom.renderInline(containerId, request, options?) / finalizeAll(containerIds?) — inline checkbox flow.

TypeScript types for every request/response/option shape ship with the package.

Local development

npm install
npm run start

Then open http://127.0.0.1:3000/ for the dialog demo or http://127.0.0.1:3000/inline.html for the inline demo. The Vite config also exposes a /cors-proxy?url=... endpoint so the demos can hit the Clickterm API directly from localhost.

Note on hot reload. If rollup's watch doesn't pick up changes reliably, this workaround works: npx nodemon --watch src --ext ts --exec "npm run start". No project-side changes needed.

Scripts

• npm run start — runs watch:dev (rollup) and vite in parallel. Dev bundle written to public/dist/index.js.
• npm run build — production build. Emits UMD, ESM, CJS, and .d.ts bundles under dist/.
• npm run build:dev — one-shot dev bundle into public/dist/index.js.
• npm run watch:dev — rollup in watch mode without starting Vite.
• npm run types — emit .d.ts files only.

Project layout

• src/index.ts — public exports (ClicktermClient, ClicktermDialog, ClicktermDom).
• src/widget.ts — orchestrates the clickwrap lifecycle (fetch template → render → submit agreement).
• src/client.ts — HttpService wrapping the Clickterm /public-client/v1/clickwrap endpoints.
• src/ui/ — DOM rendering. Uses closed Shadow DOM for style isolation; CSS lives in assets/style.css and is imported as a string.
• src/inline/ — inline-mode registry and handle implementations.
• src/translations.ts — lazy load of dialog translations from app.clickterm.com/sdk/clickterm-widget-translations.json.

Release

1. Bump version in package.json.
2. Commit and push to main.
3. Create a matching v* git tag (e.g. v2.3.0) and push it.

The publish.yml workflow runs on any v* tag: it builds and runs npm publish using the NPM_TOKEN repo secret.

License

MIT