![\"YourApp\"](\"https://yourapp.com/logo.png\"){kind=logo}
\n Order Confirmation
Your order #12345 is on its way.
'\n})\n\nconsole.log(result.success) // true/false - whether email was sent\nconsole.log(result.messageId) // \"msg_abc123...\" - unique message identifier\n\n// Send with plain text fallback (recommended for better deliverability)\nconst { success, messageId } = await blink.notifications.email({\n to: 'customer@example.com',\n subject: 'Welcome to our platform!',\n html: 'Welcome!
Thanks for joining us.
',\n text: 'Welcome!\\n\\nThanks for joining us.' // Plain text version\n})\n\n// Send an email with attachments and custom branding\nconst result = await blink.notifications.email({\n to: ['team@example.com', 'manager@example.com'],\n from: 'invoices@mycompany.com', // Must be valid email address\n replyTo: 'support@mycompany.com',\n subject: 'New Invoice #12345',\n html: `\n\n
\n `,\n text: 'Invoice Ready\\n\\nPlease find the invoice attached.',\n cc: 'accounting@mycompany.com',\n bcc: 'archive@mycompany.com',\n attachments: [\n { \n url: 'https://mycompany.com/invoices/12345.pdf',\n filename: 'Invoice-12345.pdf', // Custom filename\n type: 'application/pdf' // MIME type (optional)\n },\n {\n url: 'https://mycompany.com/terms.pdf',\n filename: 'Terms-of-Service.pdf'\n }\n ]\n})\n\nconsole.log(`Email ${result.success ? 'sent' : 'failed'}`)\nconsole.log(`Message ID: ${result.messageId}`)\n\n// Send to multiple recipients with different recipient types\nconst { success, messageId } = await blink.notifications.email({\n to: ['customer1@example.com', 'customer2@example.com'],\n cc: ['manager@example.com'],\n bcc: ['audit@example.com', 'backup@example.com'],\n from: 'notifications@mycompany.com',\n subject: 'Monthly Newsletter',\n html: 'Invoice Ready
\nPlease find the invoice attached.
\nThis Month\\'s Updates
Here are the highlights...
'\n})\n\n// Dynamic email content with user data\nconst user = await blink.auth.me()\nconst welcomeEmail = await blink.notifications.email({\n to: user.email,\n from: 'welcome@mycompany.com',\n subject: `Welcome ${user.displayName}!`,\n html: `\nHi ${user.displayName}!
\nWelcome to our platform. Your account is now active.
\nAccount ID: ${user.id}
\n Get Started\n `,\n text: `Hi ${user.displayName}!\\n\\nWelcome to our platform. Your account is now active.\\nAccount ID: ${user.id}\\n\\nGet Started: https://myapp.com/dashboard`\n})\n\n// Comprehensive error handling with detailed error information\ntry {\n const result = await blink.notifications.email({\n to: 'customer@example.com',\n subject: 'Important Update',\n html: 'This is an important update about your account.
'\n })\n \n if (result.success) {\n console.log('β Email sent successfully!')\n console.log('π§ Message ID:', result.messageId)\n } else {\n console.error('β Email failed to send')\n // Handle failed send (retry logic, fallback notification, etc.)\n }\n \n} catch (error) {\n if (error instanceof BlinkNotificationsError) {\n console.error('β Email error:', error.message)\n \n // Common error scenarios:\n // - \"The 'to', 'subject', and either 'html' or 'text' fields are required.\"\n // - \"Invalid email address format\"\n // - \"Attachment URL must be accessible\"\n // - \"Failed to send email: Rate limit exceeded\"\n \n // Handle specific error types\n if (error.message.includes('Rate limit')) {\n // Implement retry with backoff\n console.log('β³ Rate limited, will retry later')\n } else if (error.message.includes('Invalid email')) {\n // Log invalid email for cleanup\n console.log('π§ Invalid email address, removing from list')\n }\n } else {\n console.error('β Unexpected error:', error)\n }\n}\n\n// Email validation and best practices\nconst validateAndSendEmail = async (recipient: string, subject: string, content: string) => {\n // Basic validation\n if (!recipient.includes('@') || !subject.trim() || !content.trim()) {\n throw new Error('Invalid email parameters')\n }\n \n try {\n const result = await blink.notifications.email({\n to: recipient,\n from: 'noreply@mycompany.com',\n subject: subject,\n html: `\n\n
\n `,\n text: content.replace(/<[^>]*>/g, '') // Strip HTML for text version\n })\n \n return result\n } catch (error) {\n console.error(`Failed to send email to ${recipient}:`, error)\n throw error\n }\n}\n\n// Usage with validation\ntry {\n const result = await validateAndSendEmail(\n 'customer@example.com',\n 'Account Verification Required',\n '\n
\n My Company
\n\n ${content}\n
\n \n
\n Β© 2024 My Company. All rights reserved.
\n \nPlease verify your account by clicking the link below.
Verify Account'\n )\n console.log('Email sent with ID:', result.messageId)\n} catch (error) {\n console.error('Email validation or sending failed:', error.message)\n}\n\n// Bulk email sending with error handling\nconst sendBulkEmails = async (recipients: string[], subject: string, htmlContent: string) => {\n const results = []\n \n for (const recipient of recipients) {\n try {\n const result = await blink.notifications.email({\n to: recipient,\n from: 'newsletter@mycompany.com',\n subject,\n html: htmlContent,\n text: htmlContent.replace(/<[^>]*>/g, '')\n })\n \n results.push({ \n recipient, \n success: result.success, \n messageId: result.messageId \n })\n \n // Rate limiting: wait between sends\n await new Promise(resolve => setTimeout(resolve, 100))\n \n } catch (error) {\n results.push({ \n recipient, \n success: false, \n error: error.message \n })\n }\n }\n \n return results\n}\n\n// Response format details:\n// β Success response: { success: true, messageId: \"msg_abc123...\", from: \"noreply@project.blink-email.com\", to: [\"recipient@example.com\"], subject: \"Email Subject\", timestamp: \"2024-01-20T10:30:00.000Z\" }\n// β The method throws BlinkNotificationsError on failure\n// π Error types: validation errors, rate limits, network issues, invalid attachments\n\n// API Response Format:\n// The notifications API returns data directly (not wrapped in {data: ..., error: ...})\n// This is consistent with other Blink APIs like database and storage\n// All Blink APIs follow this pattern for clean, predictable responses\n\n// Best practices:\n// 1. Always include both HTML and text versions for better deliverability\n// 2. Use valid email addresses for 'from' field (not display names)\n// 3. Keep HTML simple with inline CSS for email client compatibility\n// 4. Handle rate limits with retry logic\n// 5. Validate email addresses before sending\n// 6. Use message IDs for tracking and debugging\n// 7. Include unsubscribe links for compliance\n```\n\n### Analytics Operations\n\n```typescript\n// π₯ Analytics (NEW!) - Automatic pageview tracking + custom events\n// Pageviews are tracked automatically on initialization and route changes\n\n// Log custom events - context data is added automatically\nblink.analytics.log('button_clicked', {\n button_id: 'signup',\n campaign: 'summer_sale'\n})\n\n// All events automatically include:\n// - timestamp, project_id, user_id, user_email, session_id\n// - pathname (current page), referrer, screen_width\n// - device/browser/OS info (parsed server-side)\n// - channel detection (Organic Search, Social, Direct, etc.)\n// - UTM parameters (source, medium, campaign, content, term)\n// - UTM persistence for attribution tracking across sessions\n\n// Control analytics\nblink.analytics.disable()\nblink.analytics.enable()\nconst isEnabled = blink.analytics.isEnabled()\n\n// Clear attribution data (e.g., when user logs out)\nblink.analytics.clearAttribution()\n\n// Features: Privacy-first, offline support, event batching, session management\n// Attribution: UTM params persist across sessions for conversion tracking\n\n// How UTM persistence works:\n// 1. User visits with ?utm_source=google&utm_campaign=summer_sale\n// 2. These params are saved to localStorage for attribution\n// 3. Future events (even days later) include these UTM params\n// 4. Perfect for tracking which campaigns drive conversions\n// 5. New UTM params override old ones (last-touch model available)\n```\n\n### Realtime Operations\n\n**π Zero-Boilerplate Connection Management!** \nAll connection states, queuing, and reconnection are handled automatically. No more \"CONNECTING state\" errors!\n\n**β οΈ React Users**: See the [React + Realtime Connections](#react--realtime-connections) section below for proper async cleanup patterns to avoid \"Subscription cancelled\" errors.\n\n```typescript\n// π₯ Real-time Messaging & Presence (NEW!)\n// Perfect for chat apps, live collaboration, multiplayer games, and live updates\n\n// Simple subscribe and publish (most common pattern)\nconst unsubscribe = await blink.realtime.subscribe('chat-room', (message) => {\n console.log('New message:', message.data)\n console.log('From user:', message.userId)\n console.log('Message type:', message.type)\n})\n// message callback receives RealtimeMessage format:\n// {\n// id: '1640995200000-0',\n// type: 'chat',\n// data: { text: 'Hello!', timestamp: 1640995200000 },\n// timestamp: 1640995200000,\n// userId: 'user123',\n// metadata: { displayName: 'John' }\n// }\n\n// Publish a message to all subscribers - returns message ID\nconst messageId = await blink.realtime.publish('chat-room', 'message', {\n text: 'Hello everyone!',\n timestamp: Date.now()\n})\n// messageId is string format: '1640995200000-0'\n\n// Advanced channel usage with presence tracking\nconst channel = blink.realtime.channel('game-lobby')\n\n// Subscribe with user metadata\nawait channel.subscribe({\n userId: user.id,\n metadata: { \n displayName: user.name,\n avatar: user.avatar,\n status: 'online'\n }\n})\n\n// Listen for messages\nconst unsubMessage = channel.onMessage((message) => {\n if (message.type === 'chat') {\n addChatMessage(message.data)\n } else if (message.type === 'game-move') {\n updateGameState(message.data)\n }\n})\n// message parameter format:\n// {\n// id: '1640995200000-0',\n// type: 'chat',\n// data: { text: 'Hello!', timestamp: 1640995200000 },\n// timestamp: 1640995200000,\n// userId: 'user123',\n// metadata: { displayName: 'John' }\n// }\n\n// Listen for presence changes (who's online)\n// Callback receives array of PresenceUser objects\nconst unsubPresence = channel.onPresence((users) => {\n console.log(`${users.length} users online:`)\n users.forEach(user => {\n console.log(`- ${user.metadata?.displayName} (${user.userId})`)\n })\n updateOnlineUsersList(users)\n})\n// users parameter format:\n// [\n// { \n// userId: 'user123', \n// metadata: { displayName: 'John', status: 'online' },\n// joinedAt: 1640995200000,\n// lastSeen: 1640995230000\n// }\n// ]\n\n// Publish different types of messages\nawait channel.publish('chat', { text: 'Hello!' }, { userId: user.id })\nawait channel.publish('game-move', { x: 5, y: 3, piece: 'king' })\nawait channel.publish('typing', { isTyping: true })\n\n// Get current presence (one-time check)\n// Returns array of PresenceUser objects directly\nconst currentUsers = await channel.getPresence()\nconsole.log('Currently online:', currentUsers.length)\n// currentUsers is PresenceUser[] format:\n// [\n// { \n// userId: 'user123', \n// metadata: { displayName: 'John', status: 'online' },\n// joinedAt: 1640995200000,\n// lastSeen: 1640995230000\n// }\n// ]\n\n// Get message history - returns array of RealtimeMessage objects\nconst recentMessages = await channel.getMessages({ \n limit: 50,\n before: lastMessageId // Pagination support\n})\n// recentMessages is RealtimeMessage[] format:\n// [\n// {\n// id: '1640995200000-0',\n// type: 'chat',\n// data: { text: 'Hello!', timestamp: 1640995200000 },\n// timestamp: 1640995200000,\n// userId: 'user123',\n// metadata: { displayName: 'John' }\n// }\n// ]\n\n// Cleanup when done\nunsubMessage()\nunsubPresence()\nawait channel.unsubscribe()\n\n// Or use the simple unsubscribe from subscribe()\nunsubscribe()\n\n// Multiple channels for different features\nconst chatChannel = blink.realtime.channel('chat')\nconst notificationChannel = blink.realtime.channel('notifications')\nconst gameChannel = blink.realtime.channel('game-state')\n\n// Each channel is independent with its own subscribers and presence\nawait chatChannel.subscribe({ userId: user.id })\nawait notificationChannel.subscribe({ userId: user.id })\nawait gameChannel.subscribe({ userId: user.id, metadata: { team: 'red' } })\n\n// Real-time collaboration example\nconst docChannel = blink.realtime.channel(`document-${docId}`)\n\nawait docChannel.subscribe({\n userId: user.id,\n metadata: { \n name: user.name,\n cursor: { line: 1, column: 0 }\n }\n})\n\n// Broadcast cursor movements\ndocChannel.onMessage((message) => {\n if (message.type === 'cursor-move') {\n updateUserCursor(message.userId, message.data.position)\n } else if (message.type === 'text-change') {\n applyTextChange(message.data.delta)\n }\n})\n\n// Send cursor updates\nawait docChannel.publish('cursor-move', {\n position: { line: 5, column: 10 }\n}, { userId: user.id })\n\n// Send text changes\nawait docChannel.publish('text-change', {\n delta: { insert: 'Hello', retain: 5 },\n timestamp: Date.now()\n})\n\n// Presence with live cursor positions\ndocChannel.onPresence((users) => {\n users.forEach(user => {\n if (user.metadata?.cursor) {\n showUserCursor(user.userId, user.metadata.cursor)\n }\n })\n})\n\n// Auto-cleanup on page unload\nwindow.addEventListener('beforeunload', () => {\n docChannel.unsubscribe()\n})\n\n// Error handling\ntry {\n await blink.realtime.publish('restricted-channel', 'message', { data: 'test' })\n} catch (error) {\n if (error instanceof BlinkRealtimeError) {\n console.error('Realtime error:', error.message)\n }\n}\n```\n\n## π§ Advanced Usage\n\n### Error Handling\n\n```typescript\nimport { \n BlinkAuthError, \n BlinkAuthErrorCode,\n BlinkAIError, \n BlinkStorageError, \n BlinkDataError, \n BlinkRealtimeError, \n BlinkNotificationsError \n} from '@blinkdotnew/sdk'\n\n// Authentication error handling\ntry {\n const user = await blink.auth.signInWithEmail(email, password)\n} catch (error) {\n if (error instanceof BlinkAuthError) {\n switch (error.code) {\n case BlinkAuthErrorCode.EMAIL_NOT_VERIFIED:\n console.log('Email verification required')\n await blink.auth.sendEmailVerification()\n break\n case BlinkAuthErrorCode.INVALID_CREDENTIALS:\n console.error('Invalid email or password')\n break\n case BlinkAuthErrorCode.RATE_LIMITED:\n console.error('Too many attempts, try again later')\n break\n default:\n console.error('Auth error:', error.message)\n }\n }\n}\n\n// Other error types\ntry {\n const { text } = await blink.ai.generateText({ prompt: 'Hello' })\n} catch (error) {\n if (error instanceof BlinkAIError) {\n console.error('AI error:', error.message)\n }\n}\n```\n\n### Custom Configuration\n\n```typescript\nconst blink = createClient({\n projectId: 'your-project',\n baseUrl: 'https://custom-api.example.com',\n auth: {\n mode: 'headless', // 'managed' | 'headless'\n authUrl: 'https://your-auth-service.com', // Custom auth domain (for all auth endpoints)\n coreUrl: 'https://custom-core.example.com', // Custom API domain (for db, ai, storage)\n // Providers controlled via project settings\n redirectUrl: 'https://myapp.com/dashboard',\n roles: {\n admin: { permissions: ['*'] },\n editor: { permissions: ['posts.create', 'posts.update'], inherit: ['viewer'] },\n viewer: { permissions: ['posts.read'] }\n }\n },\n httpClient: {\n timeout: 30000,\n retries: 3\n }\n})\n```\n\n### TypeScript Support\n\nThe SDK is written in TypeScript and provides full type safety:\n\n```typescript\ninterface Todo {\n id: string\n title: string\n isCompleted: boolean // Will be returned as \"0\" or \"1\" string from SQLite\n userId: string // Automatically converted from snake_case user_id\n createdAt: string // Automatically converted from snake_case created_at\n}\n\n// Note: Boolean fields are returned as \"0\"/\"1\" strings from SQLite\n// Use Number(value) > 0 to check boolean values\nconst todos = await blink.db.todos.listLoading...
\n \n // Now safe to use user.id everywhere\n useEffect(() => {\n if (!user?.id) return\n \n let channel: RealtimeChannel | null = null\n \n const initApp = async () => {\n channel = blink.realtime.channel('room')\n await channel.subscribe({ userId: user.id })\n \n channel.onMessage((message) => {\n setMessages(prev => [...prev, message])\n })\n }\n \n initApp().catch(console.error)\n \n return () => {\n channel?.unsubscribe()\n }\n }, [user?.id])\n \n return Welcome {user.email}! Messages: {messages.length}
\n}\n```\n\n**Rules:**\n1. **Never return cle","readmeFilename":"README.md"}