Order Confirmation
Your order #12345 is on its way.
' }) console.log(result.success) // true/false - whether email was sent console.log(result.messageId) // "msg_abc123..." - unique message identifier // Send with plain text fallback (recommended for better deliverability) const { success, messageId } = await blink.notifications.email({ to: 'customer@example.com', subject: 'Welcome to our platform!', html: 'Welcome!
Thanks for joining us.
', text: 'Welcome!\n\nThanks for joining us.' // Plain text version }) // Send an email with attachments and custom branding const result = await blink.notifications.email({ to: ['team@example.com', 'manager@example.com'], from: 'invoices@mycompany.com', // Must be valid email address replyTo: 'support@mycompany.com', subject: 'New Invoice #12345', html: `Invoice Ready
Please find the invoice attached.
This Month\'s Updates
Here are the highlights...
' }) // Dynamic email content with user data const user = await blink.auth.me() const welcomeEmail = await blink.notifications.email({ to: user.email, from: 'welcome@mycompany.com', subject: `Welcome ${user.displayName}!`, html: `Hi ${user.displayName}!
Welcome to our platform. Your account is now active.
Account ID: ${user.id}
Get Started `, 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` }) // Comprehensive error handling with detailed error information try { const result = await blink.notifications.email({ to: 'customer@example.com', subject: 'Important Update', html: 'This is an important update about your account.
' }) if (result.success) { console.log('✅ Email sent successfully!') console.log('📧 Message ID:', result.messageId) } else { console.error('❌ Email failed to send') // Handle failed send (retry logic, fallback notification, etc.) } } catch (error) { if (error instanceof BlinkNotificationsError) { console.error('❌ Email error:', error.message) // Common error scenarios: // - "The 'to', 'subject', and either 'html' or 'text' fields are required." // - "Invalid email address format" // - "Attachment URL must be accessible" // - "Failed to send email: Rate limit exceeded" // Handle specific error types if (error.message.includes('Rate limit')) { // Implement retry with backoff console.log('⏳ Rate limited, will retry later') } else if (error.message.includes('Invalid email')) { // Log invalid email for cleanup console.log('📧 Invalid email address, removing from list') } } else { console.error('❌ Unexpected error:', error) } } // Email validation and best practices const validateAndSendEmail = async (recipient: string, subject: string, content: string) => { // Basic validation if (!recipient.includes('@') || !subject.trim() || !content.trim()) { throw new Error('Invalid email parameters') } try { const result = await blink.notifications.email({ to: recipient, from: 'noreply@mycompany.com', subject: subject, html: ` `, text: content.replace(/<[^>]*>/g, '') // Strip HTML for text version }) return result } catch (error) { console.error(`Failed to send email to ${recipient}:`, error) throw error } } // Usage with validation try { const result = await validateAndSendEmail( 'customer@example.com', 'Account Verification Required', 'Please verify your account by clicking the link below.
Verify Account' ) console.log('Email sent with ID:', result.messageId) } catch (error) { console.error('Email validation or sending failed:', error.message) } // Bulk email sending with error handling const sendBulkEmails = async (recipients: string[], subject: string, htmlContent: string) => { const results = [] for (const recipient of recipients) { try { const result = await blink.notifications.email({ to: recipient, from: 'newsletter@mycompany.com', subject, html: htmlContent, text: htmlContent.replace(/<[^>]*>/g, '') }) results.push({ recipient, success: result.success, messageId: result.messageId }) // Rate limiting: wait between sends await new Promise(resolve => setTimeout(resolve, 100)) } catch (error) { results.push({ recipient, success: false, error: error.message }) } } return results } // Response format details: // ✅ 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" } // ❌ The method throws BlinkNotificationsError on failure // 🔍 Error types: validation errors, rate limits, network issues, invalid attachments // API Response Format: // The notifications API returns data directly (not wrapped in {data: ..., error: ...}) // This is consistent with other Blink APIs like database and storage // All Blink APIs follow this pattern for clean, predictable responses // Best practices: // 1. Always include both HTML and text versions for better deliverability // 2. Use valid email addresses for 'from' field (not display names) // 3. Keep HTML simple with inline CSS for email client compatibility // 4. Handle rate limits with retry logic // 5. Validate email addresses before sending // 6. Use message IDs for tracking and debugging // 7. Include unsubscribe links for compliance ``` ### 分析操作 ```typescript // 🔥 Analytics (NEW!) - Automatic pageview tracking + custom events // Pageviews are tracked automatically on initialization and route changes // Log custom events - context data is added automatically blink.analytics.log('button_clicked', { button_id: 'signup', campaign: 'summer_sale' }) // All events automatically include: // - timestamp, project_id, session_id (no user IDs or emails) // - pathname (current page), referrer, screen_width // - device/browser/OS info (parsed server-side) // - channel detection (Organic Search, Social, Direct, etc.) // - UTM parameters (source, medium, campaign, content, term) // - UTM persistence for attribution tracking across sessions // Control analytics // createClient({ projectId, analytics: false }) → SDK analytics off from the start: nothing sent or stored // (sites hosted on Blink also get a separate page-view tag, not controlled here) blink.analytics.disable() // stops sending, clears queued events and stored IDs, remembers the opt-out blink.analytics.enable() // opts back in const isEnabled = blink.analytics.isEnabled() // Off automatically when the browser sends Do Not Track or Global Privacy Control // Clear attribution data (e.g., when user logs out) blink.analytics.clearAttribution() // Features: Privacy-first, offline support, event batching, session management // Attribution: UTM params persist across sessions for conversion tracking // How UTM persistence works: // 1. User visits with ?utm_source=google&utm_campaign=summer_sale // 2. These params are saved to localStorage for attribution // 3. Future events (even days later) include these UTM params // 4. Perfect for tracking which campaigns drive conversions // 5. New UTM params override old ones (last-touch model available) ``` ### 实时操作 **零波纹连接管理!** 所有连接状态,排队,再连接都是自动处理的. 别再犯"状态"错误了! **QQ 反应用户**: 见 [反应 + 实时连接](https://npmcn.com/package/%40blinkdotnew/sdk/#readme-react--realtime-connections) 下面的章节,用于适当的ASync清理模式,以避免“订阅已取消”错误. ```typescript // 🔥 Real-time Messaging & Presence (NEW!) // Perfect for chat apps, live collaboration, multiplayer games, and live updates // Simple subscribe and publish (most common pattern) const unsubscribe = await blink.realtime.subscribe('chat-room', (message) => { console.log('New message:', message.data) console.log('From user:', message.userId) console.log('Message type:', message.type) }) // message callback receives RealtimeMessage format: // { // id: '1640995200000-0', // type: 'chat', // data: { text: 'Hello!', timestamp: 1640995200000 }, // timestamp: 1640995200000, // userId: 'user123', // metadata: { displayName: 'John' } // } // Publish a message to all subscribers - returns message ID const messageId = await blink.realtime.publish('chat-room', 'message', { text: 'Hello everyone!', timestamp: Date.now() }) // messageId is string format: '1640995200000-0' // Advanced channel usage with presence tracking const channel = blink.realtime.channel('game-lobby') // Subscribe with user metadata await channel.subscribe({ userId: user.id, metadata: { displayName: user.name, avatar: user.avatar, status: 'online' } }) // Listen for messages const unsubMessage = channel.onMessage((message) => { if (message.type === 'chat') { addChatMessage(message.data) } else if (message.type === 'game-move') { updateGameState(message.data) } }) // message parameter format: // { // id: '1640995200000-0', // type: 'chat', // data: { text: 'Hello!', timestamp: 1640995200000 }, // timestamp: 1640995200000, // userId: 'user123', // metadata: { displayName: 'John' } // } // Listen for presence changes (who's online) // Callback receives array of PresenceUser objects const unsubPresence = channel.onPresence((users) => { console.log(`${users.length} users online:`) users.forEach(user => { console.log(`- ${user.metadata?.displayName} (${user.userId})`) }) updateOnlineUsersList(users) }) // users parameter format: // [ // { // userId: 'user123', // metadata: { displayName: 'John', status: 'online' }, // joinedAt: 1640995200000, // lastSeen: 1640995230000 // } // ] // Publish different types of messages await channel.publish('chat', { text: 'Hello!' }, { userId: user.id }) await channel.publish('game-move', { x: 5, y: 3, piece: 'king' }) await channel.publish('typing', { isTyping: true }) // Get current presence (one-time check) // Returns array of PresenceUser objects directly const currentUsers = await channel.getPresence() console.log('Currently online:', currentUsers.length) // currentUsers is PresenceUser[] format: // [ // { // userId: 'user123', // metadata: { displayName: 'John', status: 'online' }, // joinedAt: 1640995200000, // lastSeen: 1640995230000 // } // ] // Get message history - returns array of RealtimeMessage objects const recentMessages = await channel.getMessages({ limit: 50, before: lastMessageId // Pagination support }) // recentMessages is RealtimeMessage[] format: // [ // { // id: '1640995200000-0', // type: 'chat', // data: { text: 'Hello!', timestamp: 1640995200000 }, // timestamp: 1640995200000, // userId: 'user123', // metadata: { displayName: 'John' } // } // ] // Cleanup when done unsubMessage() unsubPresence() await channel.unsubscribe() // Or use the simple unsubscribe from subscribe() unsubscribe() // Multiple channels for different features const chatChannel = blink.realtime.channel('chat') const notificationChannel = blink.realtime.channel('notifications') const gameChannel = blink.realtime.channel('game-state') // Each channel is independent with its own subscribers and presence await chatChannel.subscribe({ userId: user.id }) await notificationChannel.subscribe({ userId: user.id }) await gameChannel.subscribe({ userId: user.id, metadata: { team: 'red' } }) // Real-time collaboration example const docChannel = blink.realtime.channel(`document-${docId}`) await docChannel.subscribe({ userId: user.id, metadata: { name: user.name, cursor: { line: 1, column: 0 } } }) // Broadcast cursor movements docChannel.onMessage((message) => { if (message.type === 'cursor-move') { updateUserCursor(message.userId, message.data.position) } else if (message.type === 'text-change') { applyTextChange(message.data.delta) } }) // Send cursor updates await docChannel.publish('cursor-move', { position: { line: 5, column: 10 } }, { userId: user.id }) // Send text changes await docChannel.publish('text-change', { delta: { insert: 'Hello', retain: 5 }, timestamp: Date.now() }) // Presence with live cursor positions docChannel.onPresence((users) => { users.forEach(user => { if (user.metadata?.cursor) { showUserCursor(user.userId, user.metadata.cursor) } }) }) // Auto-cleanup on page unload window.addEventListener('beforeunload', () => { docChannel.unsubscribe() }) // Error handling try { await blink.realtime.publish('restricted-channel', 'message', { data: 'test' }) } catch (error) { if (error instanceof BlinkRealtimeError) { console.error('Realtime error:', error.message) } } ``` ## 高级用途 ### 处理错误 ```typescript import { BlinkAuthError, BlinkAuthErrorCode, BlinkAIError, BlinkStorageError, BlinkDataError, BlinkRealtimeError, BlinkNotificationsError } from '@blinkdotnew/sdk' // Authentication error handling try { const user = await blink.auth.signInWithEmail(email, password) } catch (error) { if (error instanceof BlinkAuthError) { switch (error.code) { case BlinkAuthErrorCode.EMAIL_NOT_VERIFIED: console.log('Email verification required') await blink.auth.sendEmailVerification() break case BlinkAuthErrorCode.INVALID_CREDENTIALS: console.error('Invalid email or password') break case BlinkAuthErrorCode.RATE_LIMITED: console.error('Too many attempts, try again later') break default: console.error('Auth error:', error.message) } } } // Other error types try { const { text } = await blink.ai.generateText({ prompt: 'Hello' }) } catch (error) { if (error instanceof BlinkAIError) { console.error('AI error:', error.message) } } ``` ### 自定义配置 ```typescript const blink = createClient({ projectId: 'your-project', baseUrl: 'https://custom-api.example.com', auth: { mode: 'headless', // 'managed' | 'headless' authUrl: 'https://your-auth-service.com', // Custom auth domain (for all auth endpoints) coreUrl: 'https://custom-core.example.com', // Custom API domain (for db, ai, storage) // Providers controlled via project settings redirectUrl: 'https://myapp.com/dashboard', roles: { admin: { permissions: ['*'] }, editor: { permissions: ['posts.create', 'posts.update'], inherit: ['viewer'] }, viewer: { permissions: ['posts.read'] } } }, httpClient: { timeout: 30000, retries: 3 } }) ``` ### 类型脚本支持 SDK是用TypeScript写成的,并提供完全类型的安全性: ```typescript interface Todo { id: string title: string isCompleted: boolean // Will be returned as "0" or "1" string from SQLite userId: string // Automatically converted from snake_case user_id createdAt: string // Automatically converted from snake_case created_at } // Note: Boolean fields are returned as "0"/"1" strings from SQLite // Use Number(value) > 0 to check boolean values const todos = await blink.db.todos.list