@blinkdotnew/sdk 0.1.0 → 0.2.1

package/README.md

@@ -3,40 +3,49 @@
 [![npm version](https://badge.fury.io/js/%40blinkdotnew%2Fsdk.svg)](https://badge.fury.io/js/%40blinkdotnew%2Fsdk)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-**Zero-boilerplate CRUD + auth for modern SaaS/AI apps**
+**The full-stack TypeScript SDK that powers Blink AI-generated apps**
 
-Blink SDK provides a Firebase/Supabase-like experience with built-in authentication, database operations, AI capabilities, and file storage. Works seamlessly on both client-side (React, Vue, etc.) and server-side (Node.js, Deno, Edge functions).
+Blink is an AI App Developer that builds fully functional apps in seconds. This SDK (`@blinkdotnew/sdk`) is the TypeScript foundation that powers every Blink app natively, providing zero-boilerplate authentication, database operations, AI capabilities, and file storage. Works seamlessly on both client-side (React, Vue, etc.) and server-side (Node.js, Deno, Edge functions).
 
 ## 🚀 Quick Start
 
+### **Step 1: Create a Blink Project**
+Visit [blink.new](https://blink.new) and create a new project. Blink's AI agent will build your app in seconds.
+
+### **Step 2: Install the SDK**
+Use Blink's AI agent to automatically install this SDK in your Vite React TypeScript client, or install manually:
+
 ```bash
 npm install @blinkdotnew/sdk
 ```
 
+### **Step 3: Use Your Project ID**
+Get your project ID from your Blink dashboard and start building:
+
 ```typescript
 import { createClient } from '@blinkdotnew/sdk'
 
 const blink = createClient({
-  projectId: 'your-project-id',
+  projectId: 'your-blink-project-id', // From blink.new dashboard
   authRequired: true
 })
 
-// Authentication
+// Authentication (built-in)
 const user = await blink.auth.me()
 
-// Database operations
+// Database operations (zero config)
 const todos = await blink.db.todos.list({
   where: { user_id: user.id },
   orderBy: { created_at: 'desc' },
   limit: 20
 })
 
-// AI operations
+// AI operations (native)
 const { text } = await blink.ai.generateText({
   prompt: "Write a summary of the user's todos"
 })
 
-// Storage operations
+// Storage operations (instant - returns public URL directly)
 const { publicUrl } = await blink.storage.upload(
   file,
   `avatars/${user.id}.png`,
@@ -44,17 +53,31 @@ const { publicUrl } = await blink.storage.upload(
 )
 ```
 
-## 📚 Features
+## 🤖 What is Blink?
+
+**Blink is an AI App Developer** that creates fully functional applications in seconds. Simply describe what you want to build, and Blink's AI agent will:
+
+- 🏗️ **Generate complete apps** with React + TypeScript + Vite
+- 🔧 **Auto-install this SDK** with zero configuration
+- 🎨 **Create beautiful UIs** with Tailwind CSS
+- 🚀 **Deploy instantly** with authentication, database, AI, and storage built-in
+
+## 📚 SDK Features
+
+This SDK powers every Blink-generated app with:
 
 - **🔐 Authentication**: JWT-based auth with automatic token management
-- **🗄️ Database**: PostgREST-compatible CRUD operations with advanced filtering
+- **🗄️ Database**: PostgREST-compatible CRUD operations with advanced filtering  
 - **🤖 AI**: Text generation, object generation, image creation, speech synthesis, and transcription
 - **📁 Storage**: File upload, download, and management
 - **🌐 Universal**: Works on client-side and server-side
 - **📱 Framework Agnostic**: React, Vue, Svelte, vanilla JS, Node.js, Deno
 - **🔄 Real-time**: Built-in auth state management and token refresh
+- **⚡ Zero Boilerplate**: Everything works out of the box
 
-## 🛠️ Installation & Setup
+## 🛠️ Manual Installation & Setup
+
+> **💡 Tip**: If you're using Blink's AI agent, this is all done automatically for you!
 
 ### Client-side (React, Vue, etc.)
 
@@ -62,7 +85,7 @@ const { publicUrl } = await blink.storage.upload(
 import { createClient } from '@blinkdotnew/sdk'
 
 const blink = createClient({
-  projectId: 'your-project-id',
+  projectId: 'your-blink-project-id', // From blink.new dashboard
   authRequired: true // Automatic auth redirect
 })
 ```
@@ -73,7 +96,7 @@ const blink = createClient({
 import { createClient } from '@blinkdotnew/sdk'
 
 const blink = createClient({
-  projectId: 'your-project-id',
+  projectId: 'your-blink-project-id', // From blink.new dashboard
   authRequired: false // Manual token management
 })
 
@@ -146,13 +169,40 @@ const result = await blink.db.sql('SELECT * FROM todos WHERE user_id = ?', [user
 ### AI Operations
 
 ```typescript
-// Text generation
+// Text generation (simple prompt)
 const { text } = await blink.ai.generateText({
   prompt: 'Write a poem about coding',
   model: 'gpt-4o-mini',
   maxTokens: 150
 })
 
+// Text generation with image content
+const { text } = await blink.ai.generateText({
+  messages: [
+    { 
+      role: "user", 
+      content: [
+        { type: "text", text: "What do you see in this image?" },
+        { type: "image", image: "https://example.com/photo.jpg" }
+      ]
+    }
+  ]
+})
+
+// Mixed content with multiple images
+const { text } = await blink.ai.generateText({
+  messages: [
+    { 
+      role: "user", 
+      content: [
+        { type: "text", text: "Compare these two images:" },
+        { type: "image", image: "https://example.com/image1.jpg" },
+        { type: "image", image: "https://example.com/image2.jpg" }
+      ]
+    }
+  ]
+})
+
 // Structured object generation
 const { object } = await blink.ai.generateObject({
   prompt: 'Generate a user profile',
@@ -194,7 +244,7 @@ await blink.ai.streamText(
 ### Storage Operations
 
 ```typescript
-// Upload files
+// Upload files (returns public URL directly)
 const { publicUrl } = await blink.storage.upload(
   file,
   'path/to/file.jpg',
@@ -204,18 +254,8 @@ const { publicUrl } = await blink.storage.upload(
   }
 )
 
-// List files
-const files = await blink.storage.list('folder/')
-
-// Get public URL
-const url = await blink.storage.getPublicUrl('path/to/file.jpg')
-
 // Remove files
 await blink.storage.remove('file1.jpg', 'file2.jpg')
-
-// Copy/move files
-await blink.storage.copy('source.jpg', 'destination.jpg')
-await blink.storage.move('old-path.jpg', 'new-path.jpg')
 ```
 
 ## 🔧 Advanced Usage
@@ -233,6 +273,26 @@ try {
     console.error('Auth error:', error.message)
   }
 }
+
+// Image validation error handling
+try {
+  const { text } = await blink.ai.generateText({
+    messages: [
+      { 
+        role: "user", 
+        content: [
+          { type: "text", text: "What's in this image?" },
+          { type: "image", image: "http://example.com/image.jpg" } // Invalid: not HTTPS
+        ]
+      }
+    ]
+  })
+} catch (error) {
+  if (error instanceof BlinkAIError) {
+    console.error('AI validation error:', error.message)
+    // Example: "Message validation failed: Image URLs must use HTTPS protocol"
+  }
+}
 ```
 
 ### Custom Configuration
@@ -329,10 +389,15 @@ Deno.serve(async (req) => {
 
 ## 🔗 Links
 
-- **Documentation**: [https://docs.blink.new](https://docs.blink.new)
-- **GitHub**: [https://github.com/ShadowWalker2014/blink-sdk](https://github.com/ShadowWalker2014/blink-sdk)
-- **Website**: [https://blink.new](https://blink.new)
-- **Discord**: [Join our community](https://discord.gg/blink)
+- **🌟 Try Blink AI**: [https://blink.new](https://blink.new) - Build apps in seconds
+- **📚 Documentation**: [https://docs.blink.new](https://docs.blink.new)
+- **💻 GitHub**: [https://github.com/ShadowWalker2014/blink-sdk](https://github.com/ShadowWalker2014/blink-sdk)
+
+### Social Links
+- **🐦 X (Twitter)**: [https://x.com/blinkdotnew](https://x.com/blinkdotnew)
+- **💼 LinkedIn**: [https://www.linkedin.com/company/blinkdotnew](https://www.linkedin.com/company/blinkdotnew)
+- **💬 Discord**: [https://discord.gg/2RjY7wP4a8](https://discord.gg/2RjY7wP4a8)
+- **🔴 Reddit**: [https://www.reddit.com/r/blinkdotnew/](https://www.reddit.com/r/blinkdotnew/)
 
 ## 📄 License
 
@@ -340,4 +405,6 @@ MIT © Blink Team
 
 ---
 
-**Made with ❤️ by the Blink team** 
+**Made with ❤️ by the Blink team**
+
+🤖 **Ready to build your next app?** Visit [blink.new](https://blink.new) and let our AI create it for you in seconds! 

package/dist/index.d.mts

@@ -264,6 +264,15 @@ declare class BlinkStorageImpl implements BlinkStorage {
 declare class BlinkAIImpl implements BlinkAI {
     private httpClient;
     constructor(httpClient: HttpClient);
+    private readonly SUPPORTED_IMAGE_FORMATS;
+    /**
+     * Validates if a URL is a valid HTTPS image URL
+     */
+    private validateImageUrl;
+    /**
+     * Validates messages for image content
+     */
+    private validateMessages;
     /**
      * Get MIME type for audio format
      */
@@ -283,7 +292,7 @@ declare class BlinkAIImpl implements BlinkAI {
      *   prompt: "Write a poem about coding"
      * });
      *
-     * // Chat messages
+     * // Chat messages (text only)
      * const { text } = await blink.ai.generateText({
      *   messages: [
      *     { role: "system", content: "You are a helpful assistant" },
@@ -291,6 +300,33 @@ declare class BlinkAIImpl implements BlinkAI {
      *   ]
      * });
      *
+     * // With image content
+     * const { text } = await blink.ai.generateText({
+     *   messages: [
+     *     {
+     *       role: "user",
+     *       content: [
+     *         { type: "text", text: "What do you see in this image?" },
+     *         { type: "image", image: "https://example.com/photo.jpg" }
+     *       ]
+     *     }
+     *   ]
+     * });
+     *
+     * // Mixed content with multiple images
+     * const { text } = await blink.ai.generateText({
+     *   messages: [
+     *     {
+     *       role: "user",
+     *       content: [
+     *         { type: "text", text: "Compare these two images:" },
+     *         { type: "image", image: "https://example.com/image1.jpg" },
+     *         { type: "image", image: "https://example.com/image2.jpg" }
+     *       ]
+     *     }
+     *   ]
+     * });
+     *
      * // With options
      * const { text, usage } = await blink.ai.generateText({
      *   prompt: "Summarize this article",

package/dist/index.d.ts

@@ -264,6 +264,15 @@ declare class BlinkStorageImpl implements BlinkStorage {
 declare class BlinkAIImpl implements BlinkAI {
     private httpClient;
     constructor(httpClient: HttpClient);
+    private readonly SUPPORTED_IMAGE_FORMATS;
+    /**
+     * Validates if a URL is a valid HTTPS image URL
+     */
+    private validateImageUrl;
+    /**
+     * Validates messages for image content
+     */
+    private validateMessages;
     /**
      * Get MIME type for audio format
      */
@@ -283,7 +292,7 @@ declare class BlinkAIImpl implements BlinkAI {
      *   prompt: "Write a poem about coding"
      * });
      *
-     * // Chat messages
+     * // Chat messages (text only)
      * const { text } = await blink.ai.generateText({
      *   messages: [
      *     { role: "system", content: "You are a helpful assistant" },
@@ -291,6 +300,33 @@ declare class BlinkAIImpl implements BlinkAI {
      *   ]
      * });
      *
+     * // With image content
+     * const { text } = await blink.ai.generateText({
+     *   messages: [
+     *     {
+     *       role: "user",
+     *       content: [
+     *         { type: "text", text: "What do you see in this image?" },
+     *         { type: "image", image: "https://example.com/photo.jpg" }
+     *       ]
+     *     }
+     *   ]
+     * });
+     *
+     * // Mixed content with multiple images
+     * const { text } = await blink.ai.generateText({
+     *   messages: [
+     *     {
+     *       role: "user",
+     *       content: [
+     *         { type: "text", text: "Compare these two images:" },
+     *         { type: "image", image: "https://example.com/image1.jpg" },
+     *         { type: "image", image: "https://example.com/image2.jpg" }
+     *       ]
+     *     }
+     *   ]
+     * });
+     *
      * // With options
      * const { text, usage } = await blink.ai.generateText({
      *   prompt: "Summarize this article",

package/dist/index.js

@@ -1603,6 +1603,55 @@ var BlinkAIImpl = class {
   constructor(httpClient) {
     this.httpClient = httpClient;
   }
+  // Supported image formats for validation
+  SUPPORTED_IMAGE_FORMATS = ["jpg", "jpeg", "png", "gif", "webp"];
+  /**
+   * Validates if a URL is a valid HTTPS image URL
+   */
+  validateImageUrl(url) {
+    try {
+      const parsedUrl = new URL(url);
+      if (parsedUrl.protocol !== "https:") {
+        return { isValid: false, error: "Image URLs must use HTTPS protocol" };
+      }
+      const pathname = parsedUrl.pathname.toLowerCase();
+      const hasValidExtension = this.SUPPORTED_IMAGE_FORMATS.some(
+        (format) => pathname.endsWith(`.${format}`)
+      );
+      if (!hasValidExtension) {
+        return {
+          isValid: false,
+          error: `Image URL must end with a supported format: ${this.SUPPORTED_IMAGE_FORMATS.join(", ")}`
+        };
+      }
+      return { isValid: true };
+    } catch (error) {
+      return { isValid: false, error: "Invalid URL format" };
+    }
+  }
+  /**
+   * Validates messages for image content
+   */
+  validateMessages(messages) {
+    const errors = [];
+    messages.forEach((message, messageIndex) => {
+      if (Array.isArray(message.content)) {
+        message.content.forEach((item, contentIndex) => {
+          if (item.type === "image") {
+            if (!item.image || typeof item.image !== "string") {
+              errors.push(`Message ${messageIndex}, content ${contentIndex}: Image content must have a valid image URL`);
+            } else {
+              const validation = this.validateImageUrl(item.image);
+              if (!validation.isValid) {
+                errors.push(`Message ${messageIndex}, content ${contentIndex}: ${validation.error}`);
+              }
+            }
+          }
+        });
+      }
+    });
+    return { isValid: errors.length === 0, errors };
+  }
   /**
    * Get MIME type for audio format
    */
@@ -1632,7 +1681,7 @@ var BlinkAIImpl = class {
    *   prompt: "Write a poem about coding" 
    * });
    * 
-   * // Chat messages
+   * // Chat messages (text only)
    * const { text } = await blink.ai.generateText({
    *   messages: [
    *     { role: "system", content: "You are a helpful assistant" },
@@ -1640,6 +1689,33 @@ var BlinkAIImpl = class {
    *   ]
    * });
    * 
+   * // With image content
+   * const { text } = await blink.ai.generateText({
+   *   messages: [
+   *     { 
+   *       role: "user", 
+   *       content: [
+   *         { type: "text", text: "What do you see in this image?" },
+   *         { type: "image", image: "https://example.com/photo.jpg" }
+   *       ]
+   *     }
+   *   ]
+   * });
+   * 
+   * // Mixed content with multiple images
+   * const { text } = await blink.ai.generateText({
+   *   messages: [
+   *     { 
+   *       role: "user", 
+   *       content: [
+   *         { type: "text", text: "Compare these two images:" },
+   *         { type: "image", image: "https://example.com/image1.jpg" },
+   *         { type: "image", image: "https://example.com/image2.jpg" }
+   *       ]
+   *     }
+   *   ]
+   * });
+   * 
    * // With options
    * const { text, usage } = await blink.ai.generateText({
    *   prompt: "Summarize this article",
@@ -1659,6 +1735,12 @@ var BlinkAIImpl = class {
       if (!options.prompt && !options.messages) {
         throw new BlinkAIError("Either prompt or messages is required");
       }
+      if (options.messages) {
+        const validation = this.validateMessages(options.messages);
+        if (!validation.isValid) {
+          throw new BlinkAIError(`Message validation failed: ${validation.errors.join("; ")}`);
+        }
+      }
       const requestBody = {
         model: options.model,
         stream: false,
@@ -1729,6 +1811,12 @@ var BlinkAIImpl = class {
       if (!options.prompt && !options.messages) {
         throw new BlinkAIError("Either prompt or messages is required");
       }
+      if (options.messages) {
+        const validation = this.validateMessages(options.messages);
+        if (!validation.isValid) {
+          throw new BlinkAIError(`Message validation failed: ${validation.errors.join("; ")}`);
+        }
+      }
       const result = await this.httpClient.streamAiText(
         options.prompt || "",
         {