Troubleshooting

// Make sure you're initializing with correct credentials
grain.init({
  tenantId: 'your-tenant-id', // Check this is correct
  // ...other options
});

// Reduce event volume by being selective
// DON'T track every mouse move
window.addEventListener('mousemove', () => {
  grain.track('mouse_move'); // ❌ TOO MANY EVENTS
});

// DO track meaningful interactions
button.addEventListener('click', () => {
  grain.track('cta_clicked'); // ✅ GOOD
});

// Implement client-side caching
const cache = new Map();

async function fetchWithCache(endpoint) {
  if (cache.has(endpoint)) {
    return cache.get(endpoint);
  }
  
  const data = await fetch(endpoint);
  cache.set(endpoint, data);
  return data;
}

// Batch multiple queries instead of making them separately
// Use longer intervals for auto-refresh features

// Check your tenant ID matches the dashboard
grain.init({
  tenantId: 'your-tenant-id' // Verify this!
});

// Events won't be sent until consent is granted
grain.consent.grant(['analytics', 'functional']);

// Error: Cannot find module '@grainql/analytics-web'

// Solution 1: Install types (already included)
npm install @grainql/analytics-web

// Solution 2: Check tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

// Error: Property 'grain' does not exist on type 'Window'

// Solution: Extend Window interface
declare global {
  interface Window {
    grain: typeof import('@grainql/analytics-web').default;
  }
}

// For type-safe event properties
import type { EventProperties } from '@grainql/analytics-web';

interface CustomEventProps extends EventProperties {
  category: string;
  value: number;
}

grain.track<CustomEventProps>('purchase', {
  category: 'electronics',
  value: 99.99
});

// ❌ Don't do this
import grain from '@grainql/analytics-web';

// ✅ Use next/script for client-side
import Script from 'next/script';

<Script src="https://cdn.grainql.com/grain.js" />

// Events may fire twice in dev, but only once in production
useEffect(() => {
  grain.track('page_view');
}, []);

// ❌ Invalid
grain.init({ tenantId: 'abc' }); // Too short
grain.init({ tenantId: 'my tenant' }); // Spaces not allowed

// ✅ Valid
grain.init({ tenantId: 'my-tenant-123' }); // 4-32 chars, alphanumeric + hyphens

// ❌ Invalid
grain.track('My Event!'); // Special chars not allowed
grain.track(''); // Empty string

// ✅ Valid
grain.track('my_event'); // snake_case recommended
grain.track('button-clicked'); // kebab-case also ok

// ❌ Invalid
grain.track('event', {
  circular: window, // Circular references not allowed
  func: () => {}, // Functions not allowed
});

// ✅ Valid
grain.track('event', {
  category: 'value',
  count: 42,
  enabled: true,
  tags: ['a', 'b'],
  metadata: { key: 'value' }
});