API Reference

Complete reference documentation for Vibe SDK. This page covers all available functions, options, and features in both the React and JavaScript SDKs.

App Manifest

The app manifest defines your application's identity and permissions. It's required when initializing the SDK.

Interface

interface AppManifest {
    id: string;          // Unique identifier for your app
    name: string;        // Display name shown to users
    description: string; // Brief description of your app
    permissions: string[]; // Permissions your app requires (e.g., "read.contacts")
    pictureUrl?: string; // URL to your app's icon (optional)
    onetapEnabled?: boolean; // Enable one-tap login prompt (optional, default: false)
}

Properties

Property	Type	Required	Description
id	string	Yes	A unique identifier for your app. Use a consistent ID across all versions.
name	string	Yes	The display name shown to users during authentication.
description	string	Yes	A brief description of your app's purpose.
permissions	string[]	Yes	Array of permission strings your app requires (e.g., "read.contacts", "write.contacts").
pictureUrl	string	No	URL to your app's icon image. Displayed during authentication.
onetapEnabled	boolean	No	When true, enables streamlined one-tap login for returning users.

Example

import { AppManifest } from "vibe-sdk";

// Define your app manifest
const manifest: AppManifest = {
    id: "my-contacts-app",
    name: "My Contacts App",
    description: "Manage your contacts securely with end-to-end encryption",
    permissions: [
        "read.contacts",
        "write.contacts"
    ],
    pictureUrl: "https://example.com/app-icon.png",
    onetapEnabled: true
};

Initialization

Initialize the SDK to establish connection with the Vibe ecosystem and begin using its features.

React SDK

// Component Props Interface
interface VibeProviderProps {
    manifest: AppManifest;      // Your app manifest
    autoInit?: boolean;         // Auto-initialize on mount (default: true)
    children: React.ReactNode;  // Child components
}

// Usage
<VibeProvider manifest={manifest} autoInit={true}>
    {/* Your app components */}
</VibeProvider>

// Hook API
const { 
    account,        // Current user account (null if not logged in)
    isLoading,      // True during initialization
    isInVibeApp,    // Whether running in Vibe environment
    permissions,    // Granted permissions
    read,           // Function for subscriptions
    readOnce,       // Function for one-time reads
    write           // Function for writing data
} = useVibe();

JavaScript SDK

// Initialization function
function init(
    manifest: AppManifest,
    callback?: (state: VibeState) => void
): Unsubscribe;

// VibeState interface
interface VibeState {
    account: Account | null;  // Current user account (null if not logged in)
    permissions: string[];    // Granted permissions
}

// Return type - function to unsubscribe from state updates
type Unsubscribe = () => void;

Read Operations

Vibe provides two ways to read data: subscriptions (real-time updates) and one-time reads.

Subscriptions

// From useVibe() hook
function read(
    collection: string,
    filter?: Record<string, any>,
    callback?: (result: { docs: any[] }) => void
): Unsubscribe;

One-time Reads

// From useVibe() hook
function readOnce(
    collection: string,
    filter?: Record<string, any>
): Promise<{ docs: any[] }>;

Write Operations

Create or update data in a collection.

API

// From useVibe() hook
function write(
    collection: string,
    doc: Record<string, any>
): Promise<void>;

Creating a New Document

import React, { useState } from 'react';
import { useVibe } from 'vibe-react';

function AddContact() {
    const [name, setName] = useState("");
    const [email, setEmail] = useState("");
    const [isSubmitting, setIsSubmitting] = useState(false);
    const { write } = useVibe();
    
    async function handleSubmit(e) {
        e.preventDefault();
        setIsSubmitting(true);
        
        try {
            // Create a new contact document
            await write("contacts", {
                name,
                email
            });
            
            // Clear the form
            setName("");
            setEmail("");
            alert("Contact added successfully!");
        } catch (error) {
            console.error("Error adding contact:", error);
            alert("Failed to add contact.");
        } finally {
            setIsSubmitting(false);
        }
    }
    
    return (
        <form onSubmit={handleSubmit}>
            <h2>Add New Contact</h2>
            <div>
                <label>Name:</label>
                <input 
                    type="text" 
                    value={name} 
                    onChange={(e) => setName(e.target.value)} 
                    required 
                />
            </div>
            <div>
                <label>Email:</label>
                <input 
                    type="email" 
                    value={email} 
                    onChange={(e) => setEmail(e.target.value)} 
                    required 
                />
            </div>
            <button type="submit" disabled={isSubmitting}>
                {isSubmitting ? "Adding..." : "Add Contact"}
            </button>
        </form>
    );
}

Updating an Existing Document

import React, { useState } from 'react';
import { useVibe } from 'vibe-react';

function UpdateContact({ contact }) {
    const [name, setName] = useState(contact.name);
    const [email, setEmail] = useState(contact.email);
    const [isSubmitting, setIsSubmitting] = useState(false);
    const { write } = useVibe();
    
    async function handleUpdate(e) {
        e.preventDefault();
        setIsSubmitting(true);
        
        try {
            // Update the contact document
            // Note: Include the id to update an existing document
            await write("contacts", {
                id: contact.id,  // Required to update the specific document
                name,
                email
            });
            
            alert("Contact updated successfully!");
        } catch (error) {
            console.error("Error updating contact:", error);
            alert("Failed to update contact.");
        } finally {
            setIsSubmitting(false);
        }
    }
    
    return (
        <form onSubmit={handleUpdate}>
            <h2>Edit Contact</h2>
            <div>
                <label>Name:</label>
                <input 
                    type="text" 
                    value={name} 
                    onChange={(e) => setName(e.target.value)} 
                    required 
                />
            </div>
            <div>
                <label>Email:</label>
                <input 
                    type="email" 
                    value={email} 
                    onChange={(e) => setEmail(e.target.value)} 
                    required 
                />
            </div>
            <button type="submit" disabled={isSubmitting}>
                {isSubmitting ? "Updating..." : "Update Contact"}
            </button>
        </form>
    );
}

Delete Operations

Delete documents from a collection.

API

// From useVibe() hook
function write(
    collection: string,
    doc: { id: string, _delete: true }
): Promise<void>;

Example

import React from 'react';
import { useVibe } from 'vibe-react';

function ContactItem({ contact }) {
    const { write } = useVibe();
    const [isDeleting, setIsDeleting] = useState(false);
    
    async function handleDelete() {
        if (!confirm("Are you sure you want to delete this contact?")) {
            return;
        }
        
        setIsDeleting(true);
        
        try {
            // Delete the contact
            await write("contacts", {
                id: contact.id,
                _delete: true
            });
            
            // The UI will automatically update via the read subscription
        } catch (error) {
            console.error("Error deleting contact:", error);
            alert("Failed to delete contact.");
            setIsDeleting(false);
        }
    }
    
    return (
        <div className="contact-item">
            <h3>{contact.name}</h3>
            <p>{contact.email}</p>
            <button 
                onClick={handleDelete}
                disabled={isDeleting}
            >
                {isDeleting ? "Deleting..." : "Delete"}
            </button>
        </div>
    );
}

Filtering Data

Use filters to query specific data from collections based on field values.

Basic Filtering

import React, { useState, useEffect } from 'react';
import { useVibe } from 'vibe-react';

function FavoriteContacts() {
    const [favorites, setFavorites] = useState([]);
    const { account, read } = useVibe();
    
    useEffect(() => {
        if (!account) return;
        
        // Filter for favorite contacts only
        const unsubscribe = read(
            "contacts", 
            { isFavorite: true },
            (result) => {
                setFavorites(result.docs || []);
            }
        );
        
        return () => unsubscribe();
    }, [account, read]);
    
    return (
        <div>
            <h2>Favorite Contacts</h2>
            <ul>
                {favorites.map(contact => (
                    <li key={contact.id}>{contact.name} ⭐</li>
                ))}
            </ul>
        </div>
    );
}

Advanced Filtering

You can combine multiple conditions in a filter object to create more complex queries.

// Filter contacts that are both favorites and business contacts
const filter = { 
    isFavorite: true,
    category: "business"
};

// Use with read or readOnce
const unsubscribe = read("contacts", filter, (result) => {
    // Handle result
});

Environment Detection

Check if your app is running within the Vibe environment to adapt features accordingly.

API

// From useVibe() hook
const { isInVibeApp } = useVibe();

// Returns boolean - true if running inside Vibe app environment

Example

import React from 'react';
import { useVibe } from 'vibe-react';

function EnvironmentBanner() {
    const { isInVibeApp } = useVibe();
    
    if (isInVibeApp) {
        return null; // No banner needed in Vibe app
    }
    
    return (
        <div className="banner">
            <p>
                Install the Vibe app for the full experience with secure authentication 
                and automatic data syncing.
            </p>
            <a href="https://getvibe.app" className="button">
                Get Vibe
            </a>
        </div>
    );
}