@velto/tools

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

Quick Start

1. Get your token

1. Create an account on velto.tools
2. Create a new project
3. Copy your project token

2. Initialize the SDK

import velto from '@velto/tools';

await velto.init({
  token: 'your-project-token',
  debug: true, // optional, for development
});

3. Use features

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

Configuration

interface VeltoConfig {
  token: string; // Required: Your project token
  apiBaseUrl?: string; // Optional: Custom API URL (default: https://us-central1-velto-tools.cloudfunctions.net/api)
  manifestCacheDuration?: number; // Optional: Cache duration in seconds (default: 60)
  debug?: boolean; // Optional: Enable debug logs (default: false)
}

How it works

1. Token - You get one token per project from the dashboard
2. Manifest - The SDK fetches a manifest (which features are enabled, limits, etc.)
3. Cache - Manifest is cached for 60 seconds by default
4. Auto-update - When you change settings in the dashboard, the SDK picks it up automatically

Feature Management

• All features are managed in the Dashboard
• Enable/disable features with one click
• No code changes required
• If a feature is not enabled, the SDK returns a friendly error with a link to activate it

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