​
Install

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

ParameterTypeRequiredDescription
apiKeystringYesYour Future AI API key
iframeUrlstringYesURL for the Future AI iframe interface
serverUrlstringYesBase URL for REST API endpoints
websocketUrlstringYesWebSocket server URL
onSessionUpdatefunctionYesCallback for session state updates
authobjectNoAuthentication configuration
onErrorfunctionNoError 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