8.8 KiB
8.8 KiB
Cursor Extension → Vibn Integration Guide
Overview
This guide explains how to connect your Cursor extension to send session data to Vibn's Firebase backend.
Architecture Flow
Cursor Extension
↓
User codes & uses AI
↓
Extension captures:
- Model used
- Tokens consumed
- Files modified
- Time elapsed
↓
Extension sends POST request to Vibn API
↓
Vibn verifies API key
↓
Stores session in Firebase
↓
User sees data in Vibn dashboard
1. Extension Configuration
Add Settings to Extension
Users need to configure two settings in your Cursor extension:
// extension settings (package.json or settings UI)
{
"vibn.apiKey": {
"type": "string",
"default": "",
"description": "Your Vibn API key (get it from vibnai.com/connections)"
},
"vibn.apiUrl": {
"type": "string",
"default": "https://vibnai.com/api",
"description": "Vibn API endpoint"
}
}
2. Extension Code Changes
A. Get User's API Key
import * as vscode from 'vscode';
function getVibnApiKey(): string | undefined {
const config = vscode.workspace.getConfiguration('vibn');
return config.get<string>('apiKey');
}
function getVibnApiUrl(): string {
const config = vscode.workspace.getConfiguration('vibn');
return config.get<string>('apiUrl') || 'https://vibnai.com/api';
}
B. Send Session Data to Vibn
interface SessionData {
projectId?: string; // Optional: link to a specific project
startTime: string; // ISO 8601 timestamp
endTime?: string; // ISO 8601 timestamp (if session ended)
duration?: number; // seconds
model: string; // e.g., "claude-sonnet-4", "gpt-4", etc.
tokensUsed: number;
cost: number; // USD
filesModified: string[]; // Array of file paths
conversationSummary?: string; // Optional: summary of what was done
}
async function sendSessionToVibn(sessionData: SessionData): Promise<boolean> {
const apiKey = getVibnApiKey();
const apiUrl = getVibnApiUrl();
if (!apiKey) {
console.warn('Vibn API key not configured');
return false;
}
try {
const response = await fetch(`${apiUrl}/sessions/track`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
apiKey,
sessionData,
}),
});
if (!response.ok) {
const error = await response.json();
console.error('Failed to send session to Vibn:', error);
return false;
}
const result = await response.json();
console.log('Session tracked:', result.sessionId);
return true;
} catch (error) {
console.error('Error sending session to Vibn:', error);
return false;
}
}
C. Example Usage
// When a session starts
const sessionStart = {
startTime: new Date().toISOString(),
model: 'claude-sonnet-4',
tokensUsed: 0,
cost: 0,
filesModified: [],
};
// When a session ends or periodically
const sessionEnd = {
...sessionStart,
endTime: new Date().toISOString(),
duration: 1800, // 30 minutes
tokensUsed: 45000,
cost: 1.35, // $1.35
filesModified: [
'/src/components/Button.tsx',
'/src/utils/helpers.ts',
],
conversationSummary: 'Updated Button component styling and added helper functions',
};
await sendSessionToVibn(sessionEnd);
3. Dual Database Support (Transition Period)
During migration, send data to both PostgreSQL (current) and Vibn (new):
async function trackSession(sessionData: SessionData) {
// Send to PostgreSQL (existing)
await sendToPostgreSQL(sessionData);
// Send to Vibn (new)
await sendSessionToVibn(sessionData);
}
This allows:
- Existing users to continue working
- New Vibn users to get data immediately
- Gradual migration path
4. API Endpoint Details
Endpoint
POST https://vibnai.com/api/sessions/track
Request Body
{
"apiKey": "vibn_abc123def456...",
"sessionData": {
"projectId": "optional-project-id",
"startTime": "2025-01-15T10:30:00.000Z",
"endTime": "2025-01-15T11:00:00.000Z",
"duration": 1800,
"model": "claude-sonnet-4",
"tokensUsed": 45000,
"cost": 1.35,
"filesModified": [
"/src/components/Button.tsx",
"/src/utils/helpers.ts"
],
"conversationSummary": "Updated Button component styling"
}
}
Response (Success - 200)
{
"success": true,
"sessionId": "abc123def456",
"message": "Session tracked successfully"
}
Response (Error - 401)
{
"error": "Invalid or inactive API key"
}
Response (Error - 500)
{
"error": "Failed to track session",
"details": "Error message here"
}
5. Testing
Local Development
# Use localhost for testing
POST http://localhost:3000/api/sessions/track
Production
# Use production URL
POST https://vibnai.com/api/sessions/track
Test API Key
For development, users can get their API key from:
http://localhost:3000/marks-account/connections
or in production:
https://vibnai.com/[workspace]/connections
6. Error Handling
Invalid API Key
- User sees: "Vibn API key is invalid. Please check your settings."
- Extension: Disable Vibn integration silently, fall back to PostgreSQL only
Network Error
- User sees: Nothing (don't interrupt their work)
- Extension: Queue sessions locally, retry later
Rate Limiting
- If we add rate limiting later, queue and retry with exponential backoff
7. User Experience
Good UX:
- ✅ Silent background syncing
- ✅ No interruptions to coding
- ✅ Optional notification when first session is tracked
- ✅ Status indicator in extension (optional)
Bad UX:
- ❌ Blocking user while sending data
- ❌ Showing errors for every failed request
- ❌ Requiring manual sync
8. Security Best Practices
DO:
- ✅ Store API key in VSCode settings (encrypted by VS Code)
- ✅ Use HTTPS for all requests
- ✅ Validate API key before each request
- ✅ Include timeout on requests (5-10 seconds)
DON'T:
- ❌ Log API keys to console
- ❌ Store API keys in plaintext files
- ❌ Send API keys in URL parameters
- ❌ Retry forever on failure
9. Migration Strategy
Phase 1: Dual Write (Now)
- Send to both PostgreSQL and Vibn
- No user impact
- Validate Vibn is receiving data correctly
Phase 2: Gradual Rollout
- New users only use Vibn
- Existing users continue with PostgreSQL
- Migration tool for old data (optional)
Phase 3: Vibn Only
- Deprecate PostgreSQL
- All users on Vibn
- Extension only sends to Vibn
10. Example: Complete Integration
// vibn-integration.ts
import * as vscode from 'vscode';
export class VibnIntegration {
private apiKey: string | undefined;
private apiUrl: string;
private queuedSessions: SessionData[] = [];
constructor() {
this.loadConfig();
this.startPeriodicSync();
}
private loadConfig() {
const config = vscode.workspace.getConfiguration('vibn');
this.apiKey = config.get<string>('apiKey');
this.apiUrl = config.get<string>('apiUrl') || 'https://vibnai.com/api';
}
async trackSession(sessionData: SessionData): Promise<void> {
if (!this.apiKey) {
console.log('Vibn not configured, skipping');
return;
}
try {
const response = await fetch(`${this.apiUrl}/sessions/track`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
apiKey: this.apiKey,
sessionData,
}),
signal: AbortSignal.timeout(10000), // 10 second timeout
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const result = await response.json();
console.log('Session tracked:', result.sessionId);
} catch (error) {
console.warn('Failed to send to Vibn, queuing:', error);
this.queuedSessions.push(sessionData);
}
}
private startPeriodicSync() {
setInterval(() => this.retryQueuedSessions(), 60000); // Every minute
}
private async retryQueuedSessions() {
if (this.queuedSessions.length === 0) return;
const session = this.queuedSessions.shift();
if (session) {
await this.trackSession(session);
}
}
}
// Export singleton
export const vibnIntegration = new VibnIntegration();
Need Help?
- Check Vibn Dashboard:
https://vibnai.com/[workspace]/connections - API Docs:
https://vibnai.com/docs/api - Support:
support@vibnai.com
Summary
- ✅ User gets API key from Vibn connections page
- ✅ User adds API key to Cursor extension settings
- ✅ Extension sends session data to Vibn API
- ✅ Vibn validates API key and stores data in Firebase
- ✅ User sees real-time data in Vibn dashboard
Simple, secure, and non-intrusive! 🚀