NPM / SDK Guide

Installation

Install the dat2ai package from npm:

npm install dat2ai

Or with Yarn:

yarn add dat2ai

Basic Setup

Import and initialize dat2ai with your site key. The init function returns a shield instance you can use to listen for events and manage the lifecycle.

import { Dat2AI } from 'dat2ai';

const shield = Dat2AI.init({
  siteKey: 'YOUR_SITE_KEY',
  apiEndpoint: 'https://dat2ai.com',
});

Replace YOUR_SITE_KEY with the key from your dat2ai dashboard (Sites > [Your Site] > Site Key).

Configuration Options

The ShieldConfig object accepts the following options when calling Dat2AI.init():

Tool Configuration

Define which forms on your page should be exposed as WebMCP tools for AI agents. Each tool maps a form to a named action with typed parameters.

const shield = Dat2AI.init({
  siteKey: 'YOUR_SITE_KEY',
  enabler: {
    tools: [
      {
        formSelector: '#contact-form',
        toolName: 'submit_contact_form',
        toolDescription: 'Submit a contact form with name, email, and message',
        autoSubmit: true,
        fields: [
          {
            selector: '#name',
            paramTitle: 'full_name',
            paramDescription: 'The full name of the person'
          },
          {
            selector: '#email',
            paramTitle: 'email_address',
            paramDescription: 'A valid email address'
          },
          {
            selector: '#message',
            paramTitle: 'message',
            paramDescription: 'The message body'
          }
        ]
      }
    ]
  }
});

If a form already has toolname and tooldescription HTML attributes set manually, dat2ai will not overwrite them. Manual configuration takes precedence.

Consent Configuration

Require user consent before AI agents can interact with your forms. When enabled, a consent banner is displayed and the user's decision is persisted in localStorage.

const shield = Dat2AI.init({
  siteKey: 'YOUR_SITE_KEY',
  consent: {
    required: true,
    bannerText: 'This site uses AI agents that may interact with forms on your behalf. Do you consent?',
    policyUrl: 'https://example.com/ai-policy',
    storageKey: 'dat2ai_consent'
  }
});

The consent decision is stored in localStorage under the configured storageKey. Users can revoke consent by clearing their browser storage or through your privacy settings page.

Rate Limiting

Configure client-side rate limiting to prevent abuse. These limits are enforced locally in addition to any server-side rate limits configured in your dashboard.

const shield = Dat2AI.init({
  siteKey: 'YOUR_SITE_KEY',
  rateLimiting: {
    maxInvocationsPerMinute: 10,
    maxPerTool: {
      'submit_contact_form': 3,
      'search_products': 20
    },
    cooldownSeconds: 60
  }
});

Client-side rate limits use a sliding window algorithm. When a limit is hit, subsequent invocations are blocked and a rate_limited event is emitted. Server-side limits are also enforced independently.

Event Listeners

Subscribe to shield events for custom logging, analytics, or UI feedback. The event listener API works even in offline mode.

const shield = Dat2AI.init({ siteKey: 'YOUR_SITE_KEY' });

// Listen for all events
shield.on('event', (event) => {
  console.log('Event:', event.type, event.toolName);
});

// Listen for specific event types
shield.on('invocation', (event) => {
  console.log('Tool invoked:', event.toolName, 'by', event.agentType);
});

shield.on('consent', (event) => {
  console.log('Consent decision:', event.decision);
});

shield.on('rate_limited', (event) => {
  console.log('Rate limited:', event.toolName);
});

Server Limit Handling

Handle server-side rate limits and plan limits with the onServerLimit callback. This fires when the dat2ai API responds with a 429 (rate limit) or 402 (plan limit) status.

const shield = Dat2AI.init({
  siteKey: 'YOUR_SITE_KEY',
  onServerLimit: (info) => {
    if (info.type === 'rate_limit') {
      console.warn('Rate limited by server. Retry after:', info.retryAfter);
    }
    if (info.type === 'plan_limit') {
      console.warn('Plan limit reached:', info.message);
      // Show upgrade prompt to site owner
    }
  }
});

TypeScript Support

dat2ai ships with full TypeScript declarations. All config objects, event types, and the shield instance are fully typed. No @types package needed.

import { Dat2AI, ShieldConfig, ShieldEvent } from 'dat2ai';
import type { ToolConfig, ConsentConfig, RateLimitConfig } from 'dat2ai';

const config: ShieldConfig = {
  siteKey: 'YOUR_SITE_KEY',
  debug: true,
};

const shield = Dat2AI.init(config);

shield.on('event', (event: ShieldEvent) => {
  console.log(event.type, event.toolName);
});

Framework Examples

import { useEffect } from 'react';
import { Dat2AI } from 'dat2ai';

function App() {
  useEffect(() => {
    const shield = Dat2AI.init({
      siteKey: 'YOUR_SITE_KEY',
    });

    return () => {
      shield.destroy();
    };
  }, []);

  return <div>{/* your app */}</div>;
}

<script setup>
import { onMounted, onUnmounted } from 'vue';
import { Dat2AI } from 'dat2ai';

let shield;

onMounted(() => {
  shield = Dat2AI.init({
    siteKey: 'YOUR_SITE_KEY',
  });
});

onUnmounted(() => {
  shield?.destroy();
});
</script>