Guia NPM / SDK

Instalacion

Instala el paquete dat2ai desde npm:

npm install dat2ai

O con Yarn:

yarn add dat2ai

Configuracion Basica

Importa e inicializa dat2ai con tu clave de sitio. La funcion init devuelve una instancia shield que puedes usar para escuchar eventos y gestionar el ciclo de vida.

import { Dat2AI } from 'dat2ai';

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

Reemplaza YOUR_SITE_KEY con la clave de tu panel de dat2ai (Sitios > [Tu Sitio] > Clave de Sitio).

Opciones de Configuracion

El objeto ShieldConfig acepta las siguientes opciones al llamar a Dat2AI.init():

Configuracion de Tools

Define que formularios de tu pagina deben exponerse como tools WebMCP para agentes de IA. Cada tool mapea un formulario a una accion nombrada con parametros tipados.

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'
          }
        ]
      }
    ]
  }
});

Si un formulario ya tiene atributos HTML toolname y tooldescription configurados manualmente, dat2ai no los sobreescribira. La configuracion manual tiene prioridad.

Configuracion de Consentimiento

Requiere consentimiento del usuario antes de que los agentes de IA interactuen con tus formularios. Cuando esta activo, se muestra un banner de consentimiento y la decision del usuario se persiste en 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'
  }
});

La decision de consentimiento se almacena en localStorage bajo la storageKey configurada. Los usuarios pueden revocar el consentimiento limpiando su almacenamiento del navegador o a traves de tu pagina de ajustes de privacidad.

Rate Limiting

Configura rate limiting del lado del cliente para prevenir abuso. Estos limites se aplican localmente ademas de cualquier limite del servidor configurado en tu panel.

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

Los limites del lado del cliente usan un algoritmo de ventana deslizante. Cuando se alcanza un limite, las invocaciones siguientes se bloquean y se emite un evento rate_limited. Los limites del servidor tambien se aplican independientemente.

Listeners de Eventos

Suscribete a eventos del shield para logging personalizado, analiticas o feedback de UI. La API de listeners funciona incluso en modo offline.

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);
});

Manejo de Limites del Servidor

Maneja rate limits y limites de plan del servidor con el callback onServerLimit. Se dispara cuando la API de dat2ai responde con estado 429 (rate limit) o 402 (limite de plan).

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
    }
  }
});

Soporte TypeScript

dat2ai incluye declaraciones TypeScript completas. Todos los objetos de configuracion, tipos de eventos y la instancia shield estan completamente tipados. No se necesita paquete @types.

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);
});

Ejemplos de Frameworks

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>