SDK Methods Reference

VeilForms.init('vf-abc123', {
  publicKey: 'eyJrdHkiOiJSU0EiLC...',
  encryption: true,
  piiStrip: true,
  debug: false
});

// Minimal initialization
VeilForms.init('vf-abc123', {
  publicKey: 'eyJrdHkiOiJSU0EiLC...'
});

// Full configuration
VeilForms.init('vf-abc123', {
  publicKey: 'eyJrdHkiOiJSU0EiLC...',
  endpoint: 'https://forms.yourdomain.com/api/submit',
  encryption: true,
  piiWarning: true,
  piiStrip: true,
  autoBind: true,
  debug: process.env.NODE_ENV === 'development'
});

const result = await VeilForms.submit({
  name: 'John Doe',
  message: 'Hello world'
});

interface SubmissionResult {
  success: boolean;
  submissionId: string;
  timestamp: number;
}

// Basic submission
try {
  const result = await VeilForms.submit({
    email: 'user@example.com',
    feedback: 'Great product!'
  });
  console.log('Submitted:', result.submissionId);
} catch (error) {
  console.error('Failed:', error.message);
}

// With form element for events
const form = document.getElementById('contact-form');
const result = await VeilForms.submit(
  { name: 'John', message: 'Hello' },
  { formElement: form }
);
// Events will dispatch on the form element

await VeilForms.track('form_viewed', {
  page: '/contact',
  referrer: document.referrer
});

// Track form view
VeilForms.track('form_impression', {
  formName: 'Contact Form',
  pageUrl: window.location.href
});

// Track field interaction
document.querySelector('input[name="email"]').addEventListener('focus', () => {
  VeilForms.track('field_focused', { field: 'email' });
});

// Track form abandonment
window.addEventListener('beforeunload', () => {
  if (formHasData && !formSubmitted) {
    VeilForms.track('form_abandoned', {
      fieldsCompleted: getCompletedFields()
    });
  }
});

VeilForms.bindForms();

// Initialize without auto-binding
VeilForms.init('vf-abc123', {
  publicKey: '...',
  autoBind: false
});

// Later, after forms are added to DOM
document.body.innerHTML += `
  <form data-veilform>
    <input name="message">
    <button type="submit">Send</button>
  </form>
`;

// Manually bind
VeilForms.bindForms();

const form = document.getElementById('my-form');
const data = VeilForms.utils.collectFormData(form);

const form = document.querySelector('form');
const data = VeilForms.utils.collectFormData(form);

console.log(data);
// { name: 'John', email: 'john@example.com', colors: ['red', 'blue'] }

// Multi-value fields (checkboxes, multi-select) become arrays

const hash = await VeilForms.utils.hashField('user@example.com', 'my-salt');

// Hash an email for duplicate detection
const emailHash = await VeilForms.utils.hashField(
  'john@example.com',
  'contact-form-2024'
);

// Same input + salt = same output
const hash1 = await VeilForms.utils.hashField('test@test.com', 'salt');
const hash2 = await VeilForms.utils.hashField('test@test.com', 'salt');
console.log(hash1 === hash2); // true

// Different salt = different output
const hash3 = await VeilForms.utils.hashField('test@test.com', 'other');
console.log(hash1 === hash3); // false

// Use case: check for duplicate submissions
const submissions = await fetchSubmissions();
const newEmailHash = await VeilForms.utils.hashField(email, formId);
const isDuplicate = submissions.some(s => s.emailHash === newEmailHash);

const detection = VeilForms.utils.detectPII({
  name: 'John Doe',
  message: 'Email me at john@example.com'
});

interface PIIDetectionResult {
  hasPII: boolean;
  fields: Array<{
    field: string;
    reason: string;
  }>;
  patterns: Array<{
    field: string;
    type: string;
  }>;
}

const data = {
  name: 'John Doe',
  feedback: 'Contact me at john@example.com or 555-123-4567',
  rating: 5
};

const result = VeilForms.utils.detectPII(data);

console.log(result);
// {
//   hasPII: true,
//   fields: [
//     { field: 'name', reason: 'field_name_suggests_pii' }
//   ],
//   patterns: [
//     { field: 'feedback', type: 'email' },
//     { field: 'feedback', type: 'phone' }
//   ]
// }

// Use for validation
if (result.hasPII && !userConsented) {
  showPIIWarning(result.patterns);
}

declare namespace VeilForms {
  interface Config {
    publicKey?: string;
    endpoint?: string;
    encryption?: boolean;
    piiWarning?: boolean;
    piiStrip?: boolean;
    autoBind?: boolean;
    debug?: boolean;
  }

  interface SubmissionResult {
    success: boolean;
    submissionId: string;
    timestamp: number;
  }

  interface SubmitOptions {
    formElement?: HTMLFormElement;
  }

  interface PIIDetectionResult {
    hasPII: boolean;
    fields: Array<{ field: string; reason: string }>;
    patterns: Array<{ field: string; type: string }>;
  }

  function init(formId: string, config?: Config): void;
  function submit(data: Record<string, unknown>, options?: SubmitOptions): Promise<SubmissionResult>;
  function track(event: string, data?: Record<string, unknown>): Promise<SubmissionResult>;
  function bindForms(): void;

  namespace utils {
    function collectFormData(form: HTMLFormElement): Record<string, unknown>;
    function hashField(value: string, salt?: string): Promise<string>;
    function detectPII(data: Record<string, unknown>): PIIDetectionResult;
  }
}

export default VeilForms;