@blinkdotnew/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,563 @@
+import { BlinkClientConfig, BlinkUser, AuthState, HttpClient, TableOperations, CreateOptions, UpsertOptions, QueryOptions, ListResponse, UpdateOptions, FilterCondition, BlinkStorage, BlinkAI, StorageUploadOptions, StorageUploadResponse, TextGenerationRequest, TextGenerationResponse, ObjectGenerationRequest, ObjectGenerationResponse, ImageGenerationRequest, ImageGenerationResponse, SpeechGenerationRequest, SpeechGenerationResponse, TranscriptionRequest, TranscriptionResponse } from '@blink/core';
+export { AuthState, AuthTokens, BlinkAI, BlinkClientConfig, BlinkStorage, BlinkUser, CreateOptions, FileObject, FilterCondition, ImageGenerationRequest, ImageGenerationResponse, ListResponse, Message, ObjectGenerationRequest, ObjectGenerationResponse, QueryOptions, SpeechGenerationRequest, SpeechGenerationResponse, StorageUploadOptions, StorageUploadResponse, TableOperations, TextGenerationRequest, TextGenerationResponse, TokenUsage, TranscriptionRequest, TranscriptionResponse, UpdateOptions, UpsertOptions } from '@blink/core';
+
+/**
+ * Blink Auth Module - Client-side authentication management
+ * Handles token storage, user state, and authentication flows
+ */
+
+type AuthStateChangeCallback = (state: AuthState) => void;
+declare class BlinkAuth {
+    private config;
+    private authState;
+    private listeners;
+    private readonly authUrl;
+    constructor(config: BlinkClientConfig);
+    /**
+     * Initialize authentication from stored tokens or URL fragments
+     */
+    initialize(): Promise<void>;
+    /**
+     * Redirect to Blink auth page
+     */
+    login(nextUrl?: string): void;
+    /**
+     * Logout and clear stored tokens
+     */
+    logout(redirectUrl?: string): void;
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get current user (sync)
+     */
+    currentUser(): BlinkUser | null;
+    /**
+     * Get current access token
+     */
+    getToken(): string | null;
+    /**
+     * Check if access token is expired based on timestamp
+     */
+    private isAccessTokenExpired;
+    /**
+     * Check if refresh token is expired based on timestamp
+     */
+    private isRefreshTokenExpired;
+    /**
+     * Get a valid access token, refreshing if necessary
+     */
+    getValidToken(): Promise<string | null>;
+    /**
+     * Fetch current user profile from API
+     */
+    me(): Promise<BlinkUser>;
+    /**
+     * Update user profile
+     */
+    updateMe(updates: Partial<BlinkUser>): Promise<BlinkUser>;
+    /**
+     * Manually set tokens (for server-side usage)
+     */
+    setToken(jwt: string, persist?: boolean): Promise<void>;
+    /**
+     * Refresh access token using refresh token
+     */
+    refreshToken(): Promise<boolean>;
+    /**
+     * Add auth state change listener
+     */
+    onAuthStateChanged(callback: AuthStateChangeCallback): () => void;
+    /**
+     * Private helper methods
+     */
+    private validateStoredTokens;
+    private setTokens;
+    private clearTokens;
+    private getStoredTokens;
+    private extractTokensFromUrl;
+    private clearUrlTokens;
+    private redirectToAuth;
+    private setLoading;
+    private updateAuthState;
+}
+
+/**
+ * Blink Database Module - Table operations and query interface
+ * Provides CRUD operations with PostgREST-compatible API
+ */
+
+declare class BlinkTable<T = any> implements TableOperations<T> {
+    private tableName;
+    private httpClient;
+    constructor(tableName: string, httpClient: HttpClient);
+    /**
+     * Create a single record
+     */
+    create(data: Partial<T>, options?: CreateOptions): Promise<T>;
+    /**
+     * Create multiple records
+     */
+    createMany(data: Partial<T>[], options?: CreateOptions): Promise<T[]>;
+    /**
+     * Upsert a single record (insert or update on conflict)
+     */
+    upsert(data: Partial<T>, options?: UpsertOptions): Promise<T>;
+    /**
+     * Upsert multiple records
+     */
+    upsertMany(data: Partial<T>[], options?: UpsertOptions): Promise<T[]>;
+    /**
+     * Get a single record by ID
+     */
+    get(id: string): Promise<T | null>;
+    /**
+     * List records with filtering, sorting, and pagination
+     */
+    list(options?: QueryOptions): Promise<ListResponse<T>>;
+    /**
+     * Update a single record by ID
+     */
+    update(id: string, data: Partial<T>, options?: UpdateOptions): Promise<T>;
+    /**
+     * Update multiple records
+     */
+    updateMany(updates: Array<{
+        id: string;
+    } & Partial<T>>, options?: UpdateOptions): Promise<T[]>;
+    /**
+     * Delete a single record by ID
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Delete multiple records based on filter
+     */
+    deleteMany(options: {
+        where: FilterCondition;
+    }): Promise<void>;
+    /**
+     * Count records matching filter
+     */
+    count(options?: {
+        where?: FilterCondition;
+    }): Promise<number>;
+    /**
+     * Check if any records exist matching filter
+     */
+    exists(options: {
+        where: FilterCondition;
+    }): Promise<boolean>;
+    /**
+     * Raw SQL query on this table (for advanced use cases)
+     */
+    sql<R = any>(query: string, params?: any[]): Promise<{
+        rows: R[];
+        columns: string[];
+        rowCount: number;
+        executionTime: number;
+    }>;
+    /**
+     * Private helper methods
+     */
+    private extractCursor;
+}
+declare class BlinkDatabase {
+    private httpClient;
+    private tables;
+    constructor(httpClient: HttpClient);
+    /**
+     * Get a table instance for any table name
+     */
+    table<T = any>(tableName: string): BlinkTable<T>;
+    /**
+     * Execute raw SQL query
+     */
+    sql<T = any>(query: string, params?: any[]): Promise<{
+        rows: T[];
+        columns: string[];
+        rowCount: number;
+        executionTime: number;
+    }>;
+    /**
+     * Execute batch SQL operations
+     */
+    batch<T = any>(statements: Array<{
+        sql: string;
+        args?: any[];
+    }>, mode?: 'read' | 'write'): Promise<{
+        results: Array<{
+            rows: T[];
+            columns: string[];
+            rowCount: number;
+        }>;
+        executionTime: number;
+        success: boolean;
+    }>;
+}
+
+/**
+ * Blink Client - Main SDK entry point
+ * Factory function and client class for the Blink SDK
+ */
+
+interface BlinkClient {
+    auth: BlinkAuth;
+    db: BlinkDatabase;
+    storage: BlinkStorage;
+    ai: BlinkAI;
+}
+/**
+ * Create a new Blink client instance
+ */
+declare function createClient(config: BlinkClientConfig): BlinkClient;
+
+/**
+ * Blink Storage Module
+ * Handles file upload and file removal
+ */
+
+declare class BlinkStorageImpl implements BlinkStorage {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Upload a file to project storage
+     *
+     * @param file - File, Blob, or Buffer to upload
+     * @param path - Destination path within project storage
+     * @param options - Upload options including upsert and progress callback
+     * @returns Promise resolving to upload response with public URL
+     *
+     * @example
+     * ```ts
+     * const { publicUrl } = await blink.storage.upload(
+     *   fileInput.files[0],
+     *   `avatars/${user.id}.png`,
+     *   {
+     *     upsert: true,
+     *     onProgress: pct => console.log(`${pct}%`)
+     *   }
+     * );
+     * ```
+     */
+    upload(file: File | Blob | Buffer, path: string, options?: StorageUploadOptions): Promise<StorageUploadResponse>;
+    /**
+     * Remove one or more files from project storage
+     *
+     * @param paths - File paths to remove
+     * @returns Promise that resolves when files are removed
+     *
+     * @example
+     * ```ts
+     * await blink.storage.remove('avatars/user1.png');
+     * await blink.storage.remove('file1.pdf', 'file2.pdf', 'file3.pdf');
+     * ```
+     */
+    remove(...paths: string[]): Promise<void>;
+}
+
+/**
+ * Blink AI Module
+ * Provides AI generation capabilities with Vercel AI SDK compatibility
+ */
+
+declare class BlinkAIImpl implements BlinkAI {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Get MIME type for audio format
+     */
+    private getMimeTypeForFormat;
+    /**
+     * Generates a text response using the Blink AI engine.
+     *
+     * @param options - An object containing either:
+     *   - `prompt`: a simple string prompt
+     *   - OR `messages`: an array of chat messages for conversation
+     *   - Plus optional model, maxTokens, temperature, signal parameters
+     *
+     * @example
+     * ```ts
+     * // Simple prompt
+     * const { text } = await blink.ai.generateText({
+     *   prompt: "Write a poem about coding"
+     * });
+     *
+     * // Chat messages
+     * const { text } = await blink.ai.generateText({
+     *   messages: [
+     *     { role: "system", content: "You are a helpful assistant" },
+     *     { role: "user", content: "Explain quantum computing" }
+     *   ]
+     * });
+     *
+     * // With options
+     * const { text, usage } = await blink.ai.generateText({
+     *   prompt: "Summarize this article",
+     *   model: "gpt-4o-mini",
+     *   maxTokens: 150,
+     *   temperature: 0.7
+     * });
+     * ```
+     *
+     * @returns Promise<TextGenerationResponse> - Object containing:
+     *   - `text`: Generated text string
+     *   - `usage`: Token usage information
+     *   - `finishReason`: Why generation stopped ("stop", "length", etc.)
+     */
+    generateText(options: TextGenerationRequest): Promise<TextGenerationResponse>;
+    /**
+     * Streams text generation with real-time updates as the AI generates content.
+     *
+     * @param options - Same as generateText: either `prompt` or `messages` with optional parameters
+     * @param onChunk - Callback function that receives each text chunk as it's generated
+     *
+     * @example
+     * ```ts
+     * // Stream with prompt
+     * await blink.ai.streamText(
+     *   { prompt: "Write a short story about space exploration" },
+     *   (chunk) => {
+     *     process.stdout.write(chunk); // Real-time output
+     *   }
+     * );
+     *
+     * // Stream with messages
+     * await blink.ai.streamText(
+     *   {
+     *     messages: [
+     *       { role: "system", content: "You are a creative writer" },
+     *       { role: "user", content: "Write a haiku about programming" }
+     *     ]
+     *   },
+     *   (chunk) => updateUI(chunk)
+     * );
+     * ```
+     *
+     * @returns Promise<TextGenerationResponse> - Final complete response with full text and metadata
+     */
+    streamText(options: TextGenerationRequest, onChunk: (chunk: string) => void): Promise<TextGenerationResponse>;
+    /**
+     * Generates structured JSON objects using AI with schema validation.
+     *
+     * @param options - Object containing:
+     *   - `prompt`: Description of what object to generate (required)
+     *   - `schema`: JSON Schema to validate the generated object
+     *   - `output`: Type of output ("object", "array", "enum")
+     *   - `enum`: Array of allowed values for enum output
+     *   - Plus optional model, signal parameters
+     *
+     * @example
+     * ```ts
+     * // Generate user profile
+     * const { object } = await blink.ai.generateObject({
+     *   prompt: "Generate a user profile for a software developer",
+     *   schema: {
+     *     type: "object",
+     *     properties: {
+     *       name: { type: "string" },
+     *       age: { type: "number" },
+     *       skills: { type: "array", items: { type: "string" } },
+     *       experience: { type: "number" }
+     *     },
+     *     required: ["name", "skills"]
+     *   }
+     * });
+     *
+     * // Generate array of items
+     * const { object } = await blink.ai.generateObject({
+     *   prompt: "List 5 programming languages",
+     *   output: "array",
+     *   schema: {
+     *     type: "array",
+     *     items: { type: "string" }
+     *   }
+     * });
+     *
+     * // Generate enum value
+     * const { object } = await blink.ai.generateObject({
+     *   prompt: "Choose the best programming language for web development",
+     *   output: "enum",
+     *   enum: ["JavaScript", "Python", "TypeScript", "Go"]
+     * });
+     * ```
+     *
+     * @returns Promise<ObjectGenerationResponse> - Object containing:
+     *   - `object`: The generated and validated JSON object/array/enum
+     *   - `usage`: Token usage information
+     *   - `finishReason`: Why generation stopped
+     */
+    generateObject(options: ObjectGenerationRequest): Promise<ObjectGenerationResponse>;
+    /**
+     * Streams structured object generation with real-time partial updates as the AI builds the object.
+     *
+     * @param options - Same as generateObject: prompt, schema, output type, etc.
+     * @param onPartial - Callback function that receives partial object updates as they're generated
+     *
+     * @example
+     * ```ts
+     * // Stream object generation with schema
+     * await blink.ai.streamObject(
+     *   {
+     *     prompt: "Generate a detailed product catalog entry",
+     *     schema: {
+     *       type: "object",
+     *       properties: {
+     *         name: { type: "string" },
+     *         price: { type: "number" },
+     *         description: { type: "string" },
+     *         features: { type: "array", items: { type: "string" } }
+     *       }
+     *     }
+     *   },
+     *   (partial) => {
+     *     console.log("Partial update:", partial);
+     *     updateProductForm(partial); // Update UI in real-time
+     *   }
+     * );
+     * ```
+     *
+     * @returns Promise<ObjectGenerationResponse> - Final complete object with metadata
+     */
+    streamObject(options: ObjectGenerationRequest, onPartial: (partial: any) => void): Promise<ObjectGenerationResponse>;
+    /**
+     * Generates images from text descriptions using AI image models.
+     *
+     * @param options - Object containing:
+     *   - `prompt`: Text description of the image to generate (required)
+     *   - `size`: Image dimensions (e.g., "1024x1024", "512x512") - varies by model
+     *   - `quality`: Image quality ("standard" or "hd")
+     *   - `n`: Number of images to generate (default: 1)
+     *   - `response_format`: Output format ("url" or "b64_json")
+     *   - Plus optional model, signal parameters
+     *
+     * @example
+     * ```ts
+     * // Basic image generation
+     * const { data } = await blink.ai.generateImage({
+     *   prompt: "A serene landscape with mountains and a lake at sunset"
+     * });
+     * console.log("Image URL:", data[0].url);
+     *
+     * // High-quality image with specific size
+     * const { data } = await blink.ai.generateImage({
+     *   prompt: "A futuristic city skyline with flying cars",
+     *   size: "1792x1024",
+     *   quality: "hd",
+     *   model: "dall-e-3"
+     * });
+     *
+     * // Multiple images
+     * const { data } = await blink.ai.generateImage({
+     *   prompt: "A cute robot mascot for a tech company",
+     *   n: 3,
+     *   size: "1024x1024"
+     * });
+     * data.forEach((img, i) => console.log(`Image ${i+1}:`, img.url));
+     *
+     * // Base64 format for direct embedding
+     * const { data } = await blink.ai.generateImage({
+     *   prompt: "A minimalist logo design",
+     *   response_format: "b64_json"
+     * });
+     * console.log("Base64 data:", data[0].b64_json);
+     * ```
+     *
+     * @returns Promise<ImageGenerationResponse> - Object containing:
+     *   - `data`: Array of generated images with url or b64_json
+     */
+    generateImage(options: ImageGenerationRequest): Promise<ImageGenerationResponse>;
+    /**
+     * Converts text to speech using AI voice synthesis models.
+     *
+     * @param options - Object containing:
+     *   - `text`: Text content to convert to speech (required)
+     *   - `voice`: Voice to use ("alloy", "echo", "fable", "onyx", "nova", "shimmer")
+     *   - `response_format`: Audio format ("mp3", "opus", "aac", "flac", "wav", "pcm")
+     *   - `speed`: Speech speed (0.25 to 4.0, default: 1.0)
+     *   - Plus optional model, signal parameters
+     *
+     * @example
+     * ```ts
+     * // Basic text-to-speech
+     * const { url } = await blink.ai.generateSpeech({
+     *   text: "Hello, welcome to our AI-powered application!"
+     * });
+     * console.log("Audio URL:", url);
+     *
+     * // Custom voice and format
+     * const { url, voice, format } = await blink.ai.generateSpeech({
+     *   text: "This is a demonstration of our speech synthesis capabilities.",
+     *   voice: "nova",
+     *   response_format: "wav",
+     *   speed: 1.2
+     * });
+     * console.log(`Generated ${format} audio with ${voice} voice:`, url);
+     *
+     * // Slow, clear speech for accessibility
+     * const { url } = await blink.ai.generateSpeech({
+     *   text: "Please listen carefully to these important instructions.",
+     *   voice: "echo",
+     *   speed: 0.8
+     * });
+     * ```
+     *
+     * @returns Promise<SpeechGenerationResponse> - Object containing:
+     *   - `url`: URL to the generated audio file
+     *   - `voice`: Voice used for generation
+     *   - `format`: Audio format
+     *   - `mimeType`: MIME type of the audio
+     */
+    generateSpeech(options: SpeechGenerationRequest): Promise<SpeechGenerationResponse>;
+    /**
+     * Transcribes audio content to text using AI speech recognition models.
+     *
+     * @param options - Object containing:
+     *   - `audio`: Audio input as URL string, base64 string, or number array buffer (required)
+     *   - `language`: Language code for transcription (e.g., "en", "es", "fr")
+     *   - `response_format`: Output format ("json", "text", "srt", "verbose_json", "vtt")
+     *   - Plus optional model, signal parameters
+     *
+     * @example
+     * ```ts
+     * // Transcribe from URL
+     * const { text } = await blink.ai.transcribeAudio({
+     *   audio: "https://example.com/meeting-recording.mp3"
+     * });
+     * console.log("Transcription:", text);
+     *
+     * // Transcribe with language hint
+     * const { text, language } = await blink.ai.transcribeAudio({
+     *   audio: "https://example.com/spanish-audio.wav",
+     *   language: "es"
+     * });
+     * console.log(`Transcribed ${language}:`, text);
+     *
+     * // Transcribe with timestamps (verbose format)
+     * const result = await blink.ai.transcribeAudio({
+     *   audio: audioFileUrl,
+     *   response_format: "verbose_json"
+     * });
+     * result.segments?.forEach(segment => {
+     *   console.log(`${segment.start}s - ${segment.end}s: ${segment.text}`);
+     * });
+     *
+     * // Transcribe from audio buffer
+     * const audioBuffer = new Array(1024).fill(0); // Your audio data
+     * const { text } = await blink.ai.transcribeAudio({
+     *   audio: audioBuffer,
+     *   language: "en"
+     * });
+     * ```
+     *
+     * @returns Promise<TranscriptionResponse> - Object containing:
+     *   - `text`: Transcribed text content
+     *   - `transcript`: Alias for text
+     *   - `segments`: Array of timestamped segments (if verbose format)
+     *   - `language`: Detected language
+     *   - `duration`: Audio duration in seconds
+     */
+    transcribeAudio(options: TranscriptionRequest): Promise<TranscriptionResponse>;
+}
+
+export { type AuthStateChangeCallback, BlinkAIImpl, type BlinkClient, BlinkDatabase, BlinkStorageImpl, BlinkTable, createClient };