futuresense-central-sdk

Official SDK for FutureSense AI Centralized Services

This SDK provides a unified interface for all 8 FutureSense AI applications to access:

• 🔐 OAuth integrations (Google, Microsoft, QuickBooks, WordPress, Facebook, LinkedIn)
• 💳 Stripe payments and subscriptions
• 📧 Email sending (Gmail/Outlook)
• 📅 Calendar integration (Google Calendar/Outlook)
• 👥 Contacts sync
• 💰 Pricing and plan management

Installation

Option 1: Local Development (Recommended for now)

Since this is a monorepo package, link it locally in each app:

# In the SDK directory
cd /path/to/centralized-payment-system/sdk
npm install
npm run build
npm link

# In each app (booker, payroll, etc.)
cd /path/to/booker/booking-app
npm link futuresense-central-sdk

Option 2: Copy SDK into each app

# Copy the built SDK into each app
cp -r sdk/ ../booker/booking-app/node_modules/futuresense-central-sdk/

Option 3: Publish to npm

# First time setup (one-time)
npm login

# Publish (from sdk directory)
cd /path/to/centralized-payment-system/sdk
npm run build
npm publish --access public

# Then in each app:
npm install futuresense-central-sdk

Note: Publishing requires npm account with access to the @futuresense scope.

Quick Start

1. Initialize the SDK

import { FutureSenseAPI } from 'futuresense-central-sdk';
import { getAuth } from 'firebase/auth';

// Create SDK instance
const api = new FutureSenseAPI({
  appId: 'booker', // Your app ID: 'booker', 'payroll', 'invoicer', etc.
  getAuthToken: async () => {
    const user = getAuth().currentUser;
    if (!user) throw new Error('User not authenticated');
    return await user.getIdToken();
  },
  baseURL: 'https://paymentgateway.futuresenseai.com/api' // Optional, defaults to this
});

2. Use the API

// OAuth - Initiate Google Sign-In
const { authUrl } = await api.oauth.initiateGoogle('/dashboard');
window.location.href = authUrl;

// Get all connected integrations
const { connections } = await api.oauth.getConnections();
console.log(connections); // [{ provider: 'google', connectedAt: '...' }]

// Create calendar event
const result = await api.calendar.createEvent({
  title: 'Team Meeting',
  start: '2025-01-15T10:00:00Z',
  end: '2025-01-15T11:00:00Z',
  attendees: ['[email protected]']
});

// Send email
await api.email.send({
  to: '[email protected]',
  subject: 'Booking Confirmation',
  body: 'Your appointment has been confirmed!'
});

// Create subscription checkout
const { url } = await api.subscriptions.createCheckout({
  planId: 'pro-plan',
  priceId: 'price_1234567890',
  successUrl: '/success',
  cancelUrl: '/cancel'
});
window.location.href = url;

// Get subscription status
const status = await api.subscriptions.getStatus();
if (status.active) {
  console.log('User has active subscription!');
}

// Get pricing
const pricing = await api.pricing.getForApp();
console.log(pricing.tiers);

API Reference

OAuth Integration

// Initiate OAuth flow
api.oauth.initiateGoogle(returnUrl?: string)
api.oauth.initiateMicrosoft(returnUrl?: string)
api.oauth.initiateQuickBooks(returnUrl?: string)
api.oauth.initiateWordPress(returnUrl?: string)
api.oauth.initiateFacebook(returnUrl?: string)
api.oauth.initiateLinkedIn(returnUrl?: string)

// Manage connections
api.oauth.getConnections()
api.oauth.disconnect(provider: OAuthProvider)
api.oauth.getToken(provider: OAuthProvider)

Calendar Integration

api.calendar.createEvent({
  title: string,
  description?: string,
  start: string, // ISO date string
  end: string,
  timeZone?: string,
  attendees?: string[],
  location?: string
})

Email Integration

api.email.send({
  to: string | string[],
  subject: string,
  body: string,
  html?: string,
  attachments?: Array<{
    filename: string,
    content: string,
    encoding?: string
  }>
})

Contacts Integration

api.contacts.list({
  limit?: number,
  searchTerm?: string
})

Payments

// Create payment intent (for Elements)
api.payments.createIntent({
  amount: number, // in cents
  currency?: string,
  description?: string,
  metadata?: Record<string, string>
})

// Create checkout session (redirect)
api.payments.createCheckout({
  amount: number,
  currency?: string,
  description?: string,
  successUrl?: string,
  cancelUrl?: string
})

Subscriptions

// Create subscription checkout
api.subscriptions.createCheckout({
  planId: string,
  priceId: string,
  successUrl?: string,
  cancelUrl?: string
})

// Manage subscriptions
api.subscriptions.createPortal(returnUrl?: string)
api.subscriptions.getStatus()
api.subscriptions.getAll()
api.subscriptions.cancel(cancelAtPeriodEnd?: boolean)
api.subscriptions.reactivate()
api.subscriptions.pause()
api.subscriptions.resume()
api.subscriptions.update(newPriceId: string)

// Payment methods
api.subscriptions.getPaymentMethods()
api.subscriptions.setDefaultPaymentMethod(paymentMethodId: string)
api.subscriptions.deletePaymentMethod(paymentMethodId: string)

// Invoices
api.subscriptions.getInvoices(limit?: number)
api.subscriptions.getUpcomingInvoice()

Pricing

api.pricing.getPublic() // All apps, public pricing
api.pricing.getForApp() // Current app's pricing
api.pricing.getAllApps() // All apps with pricing

Migration Guide

Before (Local Implementation)

// OLD - Booker app with local Stripe
import { httpsCallable } from 'firebase/functions';
import { functions } from './firebase/config';

const createPaymentIntent = httpsCallable(functions, 'createPaymentIntent');
const result = await createPaymentIntent({ amount: 5000 });

After (Using SDK)

// NEW - Using centralized SDK
import { api } from './services/api'; // Your initialized SDK instance

const result = await api.payments.createIntent({ amount: 5000 });

TypeScript Support

This SDK is written in TypeScript and includes full type definitions:

import {
  FutureSenseAPI,
  OAuthProvider,
  SubscriptionStatus,
  PaymentMethod,
  CalendarEvent
} from 'futuresense-central-sdk';

// Full IntelliSense and type checking
const api = new FutureSenseAPI({ ... });
const status: SubscriptionStatus = await api.subscriptions.getStatus();

Error Handling

All methods return promises and throw errors on failure:

try {
  const result = await api.oauth.initiateGoogle();
  window.location.href = result.authUrl;
} catch (error) {
  console.error('OAuth initiation failed:', error.message);
  // Handle error (show notification, etc.)
}

Environment Variables

The SDK uses the centralized API at https://paymentgateway.futuresenseai.com/api by default.

For local development, override the base URL:

const api = new FutureSenseAPI({
  appId: 'booker',
  baseURL: 'http://localhost:5001/paymentgateway-ab783/us-central1/api',
  getAuthToken: ...
});

Support

• Documentation: See /centralized-payment-system/CLAUDE.md
• Issues: Contact FutureSense AI team
• Email: [email protected]

License

MIT © FutureSense AI