@chamelioai/clickwrap-sdk

A zero-dependency, headless TypeScript client for integrating Clickwraps securely into any web application.

Installation

This is a public npm package published under the @chamelioai scope.

npm install @chamelioai/clickwrap-sdk

Quick Start

import { ClickwrapClient } from '@chamelioai/clickwrap-sdk';

// Initialize client
const client = new ClickwrapClient({ publicKey: 'your_public_api_key' });
const slug = 'terms-of-service';
const userEmail = '[email protected]';

// Check if the user already accepted
const { accepted, clickwrapVersionId } = await client.status({ slug, userIdentifier: userEmail });

if (!accepted) {
  // Fetch the agreement content (Markdown or HTML)
  const terms = await client.get({ slug });
  // terms.content      — Markdown source
  // terms.contentHtml  — pre-rendered HTML

  // Record acceptance on click
  await client.capture({
    slug,
    versionId: terms.clickwrapVersionId,
    userIdentifier: userEmail,
    eventType: 'accepted',
  });
}

API

new ClickwrapClient(config)

| Option | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------- | | publicKey | string | Yes | Your organisation's public API key |

client.get({ slug })

Fetches the active clickwrap version for the given slug.

Returns: Promise<ClickwrapData>

| Field | Type | Description | | -------------------- | -------- | -------------------------------------- | | slug | string | The clickwrap slug | | title | string | Display title | | content | string | Agreement content as Markdown | | contentHtml | string | Agreement content as pre-rendered HTML | | clickwrapVersionId | number | Active version ID | | versionNumber | number | Human-readable version number |

client.status({ slug, userIdentifier })

Checks whether a user has already accepted the clickwrap.

Returns: Promise<ClickwrapStatus>

client.capture({ slug, versionId, userIdentifier, eventType, metadata? })

Records a consent event.

| Param | Type | Required | | ---------------- | ------------------------------------- | -------- | | slug | string | Yes | | versionId | number | Yes | | userIdentifier | string | Yes | | eventType | 'accepted' \| 'checked' \| 'viewed' | Yes | | metadata | Record<string, unknown> | No |

Returns: Promise<void>

Types

All types are exported and can be used in your own code:

import type { CaptureParams, ClickwrapData, ClickwrapStatus, GetParams, StatusParams } from '@chamelioai/clickwrap-sdk';

Error Handling

import { ClickwrapError, ClickwrapNotFoundError, InactiveVersionCaptureError } from '@chamelioai/clickwrap-sdk';

try {
  await client.get({ slug: 'unknown-slug' });
} catch (err) {
  if (err instanceof ClickwrapNotFoundError) {
    // 404 — slug not found or no active version
  } else if (err instanceof InactiveVersionCaptureError) {
    // 422 — attempted to capture against an inactive version
  } else if (err instanceof ClickwrapError) {
    // other API error — check err.status
  }
}