Get started

The Future AI SDK provides a WebSocket-based session-like system for real-time communication with the Future AI platform. It processes email content using AI to extract valuable insights about user interests and meaningful contacts.

Install

npm

   npm install @future-sdk/future-js

Prerequisites

• Future AI API Key
• Node.js environment
• Access to Future AI services

API key & SDK configuration

To get started, you need to login to your account on FutureAI and create a new Api key. You will get an API key, and the necesery config to authenticate your requests.

Quickstart

import { startFutureSession } from '@futureai/sdk';
const session = await startFutureSession({
  apiKey: 'YOUR_API_KEY',
  iframeUrl: 'https://iframe.futureai.com',
  serverUrl: 'https://api.futureai.com',
  websocketUrl: 'wss://ws.futureai.com',
  onSessionUpdate: (session) => {
    console.log('Session updated:', session);
  },
  auth: {
    token: 'USER_AUTH_TOKEN' // Optional
  },
  onError: (error) => {
    console.error('Error:', error);
  }
});

Configuration Options

Parameter	Type	Required	Description
apiKey	string	Yes	Your Future AI API key
iframeUrl	string	Yes	URL for the Future AI iframe interface
serverUrl	string	Yes	Base URL for REST API endpoints
websocketUrl	string	Yes	WebSocket server URL
onSessionUpdate	function	Yes	Callback for session state updates
auth	object	No	Authentication configuration
onError	function	No	Error handling callback

Authentication flow

1. Initial connection

{
    "id": "session_id",
    "version": 1,
    "ended": false,
    "merchantId": "merchant_id",
    "userId": null,
    "lastEventName": "SessionStarted"
}

2. Google OAuth2 Authentication

{
    "id": "session_id",
    "version": 2,
    "ended": false,
    "merchantId": "merchant_id",
    "userId": null,
    "lastEventName": "LinkedAccountCreated"
}

3. User Authentication

{
    "id": "session_id",
    "version": 3,
    "ended": false,
    "merchantId": "merchant_id",
    "userId": null,
    "lastEventName": "UserAuthenticated",
    "userAccessToken": "jwt_token"
}

4. Email Analysis Results

{
    "id": "session_id",
    "version": 4,
    "ended": false,
    "merchantId": "merchant_id",
    "userId": "user_id",
    "lastEventName": "UserGenerativeResults",
    "userAccessToken": "jwt_token",
    "results": [/* interests and connections */]
}

Future Button Implementation

Adding the Button

<div class="future-button"></div>

Future.createFutureButton({
    container: '.future-button',
    sessionId: session.id,
    merchantFlowId: 'YOUR_MERCHANT_FLOW_ID'
});

Error Handling

Error Response Cases

Invalid API Key

{
    success: false,
    error: {
        code: 'INVALID_MERCHANT',
        message: 'Merchant not found. API key is invalid'
    }
}

Missing API Key

{
    success: false,
    error: {
        code: 'API_KEY_REQUIRED',
        message: 'API key is required'
    }
}

Invalid Authentication Token

{
    success: false,
    error: {
        code: 'INVALID_CREDENTIALS',
        message: 'Invalid authentication token'
    }
}

Internal Server Error

{
    success: false,
    error: {
        code: 'INTERNAL_ERROR',
        message: 'Internal error'
    }
}

Implementation Example

import { startFutureSession } from '@futureai/sdk';
// With new session
const session = await startFutureSession({
    apiKey: 'YOUR_API_KEY',
    onSessionUpdate: (session) => {
        switch(session.lastEventName) {
            case 'SessionStarted':
                console.log('Session initialized');
                // Initialize button
                Future.createFutureButton({
                    container: '.future-button',
                    sessionId: session.id,
                    merchantFlowId: process.env.MERCHANT_FLOW_ID
                });
                break;
            case 'LinkedAccountCreated':
                console.log('Google account linked');
                break;
            case 'UserAuthenticated':
                console.log('User authenticated');
                localStorage.setItem('userToken', session.userAccessToken);
                break;
            case 'UserGenerativeResults':
                console.log('Results ready:', session.results);
                break;
        }
    },
    onError: handleAuthError
});
function handleAuthError(error) {
    if (!error.success) {
        switch (error.error.code) {
            case 'API_KEY_REQUIRED':
                console.error('API key must be provided');
                break;
            case 'INVALID_MERCHANT':
                console.error('Invalid API key provided');
                break;
            case 'INVALID_CREDENTIALS':
                console.error('Invalid or expired authentication token');
                localStorage.removeItem('userToken');
                break;
            case 'INTERNAL_ERROR':
                console.error('System error occurred:', error.error.message);
                break;
        }
    }
}

Results Structure

interface Interest {
    interest: string;
    connections: Array<{
        name: string;
        email: string;
        score: number | null;
        relationship: string;
    }>;
}

Best Practices

1. Always handle session updates through the onSessionUpdate callback
2. Implement proper error handling using the onError callback
3. Store and manage user tokens appropriately
4. Handle reconnection scenarios
5. Validate configuration before initializing
6. Implement proper cleanup on errors