velto-tools-sdk

One package. Everything in the dashboard.

VELTO-TOOLS is a single npm package that you integrate into any website or app. Everything else (activation, payment, configuration) happens in the VELTO-TOOLS Dashboard.

Features

• 📝 Forms - Contact forms, feedback, submissions ✅
• 📧 Newsletter - Email subscriptions ✅
• 📊 Analytics - Lightweight event tracking ✅
• 📅 Booking - Appointment scheduling ✅
• 📄 CMS-Lite - Simple key-value content management ✅
• 📁 Files - User uploads with signed URLs ✅
• 🔗 Webhooks - Event-based integrations ✅
• 🤖 Autoresponder - Automated email templates ✅

Installation

npm install velto-tools-sdk

Quick Start (3 Schritte)

1. Token aus dem Dashboard kopieren

1. Gehe zu velto.tools/dashboard
2. Erstelle ein Projekt (falls noch nicht geschehen)
3. Kopiere deinen Project Token aus dem Dashboard

2. SDK initialisieren

Im Browser (ES Modules):

<script type="importmap">
{
  "imports": {
    "velto-tools-sdk": "https://unpkg.com/velto-tools-sdk@latest/dist/index.js"
  }
}
</script>
<script type="module">
  import velto from 'velto-tools-sdk';
  
  // Einfach nur Token - fertig!
  await velto.init({
    token: 'dein-token-hier'
  });
</script>

Mit npm (Node.js/Bundler):

npm install velto-tools-sdk

import velto from 'velto-tools-sdk';

// Einfach nur Token - fertig!
await velto.init({
  token: 'dein-token-hier'
});

Das war's! Die SDK lädt automatisch die Konfiguration und aktivierten Features.

3. Features verwenden

Alle Features werden automatisch geladen - du musst nichts konfigurieren!

Forms

const result = await velto.forms.submit('contact', {
  name: 'John Doe',
  email: '[email protected]',
  message: 'Hello!',
});

if (result.success) {
  console.log('Form submitted:', result.data.entryId);
} else {
  console.error('Error:', result.error.message);
}

Newsletter

const result = await velto.newsletter.subscribe({
  email: '[email protected]',
  metadata: { source: 'homepage' },
});

if (result.success) {
  console.log('Subscribed:', result.data.subscriberId);
}

Analytics

// Track custom events
await velto.analytics.track('button_click', { button: 'signup' });

// Track page views
await velto.analytics.pageView();

// Track conversions
await velto.analytics.conversion('signup', 100);

// Enable auto page view tracking (SPAs)
velto.analytics.enableAutoPageViews();

Booking

// Get available slots
const slots = await velto.booking.getAvailableSlots(
  'main-calendar',
  '2025-10-12',
  '2025-10-19'
);

// Book a slot
const booking = await velto.booking.book('main-calendar', {
  slot: { date: '2025-10-15', time: '14:00', duration: 30 },
  name: 'John Doe',
  email: '[email protected]',
  phone: '+1234567890'
});

CMS-Lite

// Get content with fallback
const title = await velto.cms.get('home.title', 'Default Title');

// Set content (requires authentication)
await velto.cms.set('home.title', 'New Title', 'text');

// Get multiple keys
const content = await velto.cms.getMultiple(['home.title', 'home.subtitle']);

Files

// Upload with file picker
const file = await velto.files.pickAndUpload({
  maxSize: 5 * 1024 * 1024, // 5MB
  allowedTypes: ['image/*', 'application/pdf'],
  folder: 'uploads'
});

console.log('File URL:', file.data.url);

Konfiguration

Minimal (empfohlen):

await velto.init({
  token: 'dein-token' // Das reicht!
});

Mit Optionen:

interface VeltoConfig {
  token: string; // ✅ Erforderlich: Token aus dem Dashboard
  apiBaseUrl?: string; // Optional: Custom API URL (Standard: https://api.velto.tools)
  manifestCacheDuration?: number; // Optional: Cache-Dauer in Sekunden (Standard: 60)
  debug?: boolean; // Optional: Debug-Logs aktivieren (Standard: false)
}

Beispiel mit Optionen:

await velto.init({
  token: 'dein-token',
  debug: true // Für Entwicklung - zeigt hilfreiche Logs
});

Wie es funktioniert

1. Token - Du kopierst einen Token aus dem Dashboard (ein Token pro Projekt)
2. Manifest - Die SDK lädt automatisch die Konfiguration (welche Features aktiviert sind, Limits, etc.)
3. Cache - Die Konfiguration wird 60 Sekunden gecacht (schneller, weniger API-Calls)
4. Auto-Update - Wenn du Einstellungen im Dashboard änderst, werden sie automatisch übernommen (nach Cache-Ablauf)

Feature-Verwaltung

• ✅ Alles im Dashboard - Alle Features werden im Dashboard verwaltet
• ✅ Ein Klick - Features mit einem Klick aktivieren/deaktivieren
• ✅ Kein Code-Update nötig - Änderungen werden automatisch übernommen
• ✅ Freundliche Fehler - Wenn ein Feature nicht aktiviert ist, bekommst du eine hilfreiche Fehlermeldung mit Link zum Aktivieren

Error Handling

All methods return a VeltoResponse:

interface VeltoResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    dashboardLink?: string; // Link to enable feature if disabled
  };
}

License

MIT

Support

• 📖 Documentation
• 💬 Discord
• ✉️ Email