How to Integrate Bolt.new with FreshBooks

1// .env.local
2FRESHBOOKS_CLIENT_ID=your_freshbooks_client_id
3FRESHBOOKS_CLIENT_SECRET=your_freshbooks_client_secret
4FRESHBOOKS_REDIRECT_URI=https://your-app.netlify.app/api/freshbooks/callback
5
6// lib/freshbooks-auth.ts
7export const FB_API_BASE = 'https://api.freshbooks.com';
8export const FB_AUTH_BASE = 'https://auth.freshbooks.com';
9
10export function buildFreshBooksAuthUrl(): string {
11  const params = new URLSearchParams({
12    client_id: process.env.FRESHBOOKS_CLIENT_ID!,
13    response_type: 'code',
14    redirect_uri: process.env.FRESHBOOKS_REDIRECT_URI!,
15  });
16  return `${FB_AUTH_BASE}/oauth/authorize?${params.toString()}`;
17}
18
19// app/api/freshbooks/callback/route.ts
20import { NextRequest, NextResponse } from 'next/server';
21import { FB_API_BASE, FB_AUTH_BASE } from '@/lib/freshbooks-auth';
22
23export async function GET(request: NextRequest) {
24  const { searchParams } = new URL(request.url);
25  const code = searchParams.get('code');
26
27  if (!code) {
28    return NextResponse.redirect(new URL('/error?message=no_code', request.url));
29  }
30
31  try {
32    const tokenRes = await fetch(`${FB_API_BASE}/auth/oauth/token`, {
33      method: 'POST',
34      headers: { 'Content-Type': 'application/json' },
35      body: JSON.stringify({
36        grant_type: 'authorization_code',
37        client_id: process.env.FRESHBOOKS_CLIENT_ID,
38        client_secret: process.env.FRESHBOOKS_CLIENT_SECRET,
39        code,
40        redirect_uri: process.env.FRESHBOOKS_REDIRECT_URI,
41      }),
42    });
43    const tokens = await tokenRes.json() as { access_token: string; refresh_token: string; token_type: string };
44
45    if (!tokens.access_token) throw new Error('No access token received');
46
47    // Get account_id from the users/me endpoint
48    const meRes = await fetch(`${FB_API_BASE}/auth/api/v1/users/me`, {
49      headers: { Authorization: `Bearer ${tokens.access_token}` },
50    });
51    const me = await meRes.json() as {
52      response: { business_memberships: Array<{ business: { account_id: string; name: string } }> };
53    };
54    const accountId = me.response.business_memberships[0]?.business?.account_id;
55
56    if (!accountId) throw new Error('No FreshBooks account found');
57
58    const response = NextResponse.redirect(new URL('/dashboard', request.url));
59    const cookieOpts = { httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'lax' as const, maxAge: 60 * 60 * 24 * 30, path: '/' };
60    response.cookies.set('fb_access_token', tokens.access_token, { ...cookieOpts, maxAge: 60 * 60 * 12 });
61    response.cookies.set('fb_refresh_token', tokens.refresh_token, cookieOpts);
62    response.cookies.set('fb_account_id', accountId, cookieOpts);
63
64    return response;
65  } catch (error) {
66    console.error('FreshBooks callback error:', error);
67    return NextResponse.redirect(new URL('/error?message=freshbooks_auth_failed', request.url));
68  }
69}

1// lib/freshbooks-api.ts
2import { cookies } from 'next/headers';
3import { FB_API_BASE } from './freshbooks-auth';
4
5const STATUS_MAP: Record<number, string> = {
6  1: 'Draft',
7  2: 'Sent',
8  4: 'Viewed',
9  5: 'Outstanding',
10  6: 'Overdue',
11  7: 'Disputed',
12  8: 'Paid',
13  9: 'Auto-Paid',
14};
15
16export { STATUS_MAP };
17
18export async function freshBooksCall<T>(
19  path: string,
20  options: RequestInit = {}
21): Promise<T> {
22  const cookieStore = cookies();
23  const accessToken = cookieStore.get('fb_access_token')?.value;
24  const accountId = cookieStore.get('fb_account_id')?.value;
25
26  if (!accessToken || !accountId) {
27    throw new Error('Not authenticated with FreshBooks');
28  }
29
30  const url = path.startsWith('http')
31    ? path
32    : `${FB_API_BASE}/accounting/account/${accountId}${path}`;
33
34  const response = await fetch(url, {
35    ...options,
36    headers: {
37      Authorization: `Bearer ${accessToken}`,
38      'Content-Type': 'application/json',
39      'Api-Version': 'alpha',
40      ...(options.headers ?? {}),
41    },
42  });
43
44  if (!response.ok) {
45    throw new Error(`FreshBooks API error: ${response.status}`);
46  }
47
48  const data = await response.json() as { response: { result: T } };
49  return data.response.result;
50}
51
52// app/api/freshbooks/invoices/route.ts
53import { NextRequest, NextResponse } from 'next/server';
54import { freshBooksCall, STATUS_MAP } from '@/lib/freshbooks-api';
55
56interface FBInvoice {
57  invoiceid: number;
58  number: string;
59  currentorganization: string;
60  create_date: string;
61  due_date: string;
62  amount: { amount: string; code: string };
63  outstanding: { amount: string; code: string };
64  v3_status: string;
65  status: number;
66}
67
68interface FBInvoicesResponse {
69  invoices: FBInvoice[];
70  total_count: number;
71  pages: number;
72}
73
74export async function GET(request: NextRequest) {
75  const { searchParams } = new URL(request.url);
76  const page = searchParams.get('page') ?? '1';
77
78  try {
79    const data = await freshBooksCall<FBInvoicesResponse>(
80      `/invoices/invoices?per_page=100&page=${page}&include[]=late_reminders`
81    );
82
83    const invoices = data.invoices.map((inv) => ({
84      id: inv.invoiceid,
85      number: inv.number,
86      clientName: inv.currentorganization,
87      createDate: inv.create_date,
88      dueDate: inv.due_date,
89      total: parseFloat(inv.amount.amount),
90      outstanding: parseFloat(inv.outstanding.amount),
91      currency: inv.amount.code,
92      status: inv.status,
93      statusLabel: STATUS_MAP[inv.status] ?? 'Unknown',
94      isPaid: inv.status === 8 || inv.status === 9,
95    }));
96
97    const totalOutstanding = invoices.filter((i) => !i.isPaid).reduce((s, i) => s + i.outstanding, 0);
98
99    return NextResponse.json({ invoices, totalOutstanding, totalCount: data.total_count, pages: data.pages });
100  } catch (error) {
101    const message = error instanceof Error ? error.message : 'Failed to fetch invoices';
102    return NextResponse.json({ error: message }, { status: 500 });
103  }
104}

1// app/api/freshbooks/time-entries/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { cookies } from 'next/headers';
4import { FB_API_BASE } from '@/lib/freshbooks-auth';
5
6export async function GET(request: NextRequest) {
7  const cookieStore = cookies();
8  const accessToken = cookieStore.get('fb_access_token')?.value;
9  // businessId is stored separately from accountId
10  const businessId = cookieStore.get('fb_business_id')?.value;
11
12  if (!accessToken || !businessId) {
13    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
14  }
15
16  const { searchParams } = new URL(request.url);
17  const billedFilter = searchParams.get('billed') ?? 'false';
18
19  try {
20    const response = await fetch(
21      `${FB_API_BASE}/timetracking/business/${businessId}/time_entries?billed=${billedFilter}&billable=true&per_page=200`,
22      { headers: { Authorization: `Bearer ${accessToken}`, 'Api-Version': 'alpha' } }
23    );
24
25    if (!response.ok) throw new Error(`FreshBooks time API error: ${response.status}`);
26
27    const data = await response.json() as {
28      time_entries: Array<{
29        id: number;
30        client_id: number;
31        project_id: number;
32        duration: number;
33        started_at: string;
34        hourly_rate: string | null;
35        billed: boolean;
36        billable: boolean;
37        note: string;
38      }>;
39    };
40
41    const entries = data.time_entries.map((e) => ({
42      id: e.id,
43      clientId: e.client_id,
44      projectId: e.project_id,
45      durationHours: Math.round((e.duration / 3600) * 100) / 100,
46      date: e.started_at?.split('T')[0],
47      hourlyRate: e.hourly_rate ? parseFloat(e.hourly_rate) : null,
48      amount: e.hourly_rate ? Math.round((e.duration / 3600) * parseFloat(e.hourly_rate) * 100) / 100 : null,
49      note: e.note,
50      billed: e.billed,
51      billable: e.billable,
52    }));
53
54    const totalUnbilledHours = entries.filter((e) => !e.billed).reduce((s, e) => s + e.durationHours, 0);
55    const totalUnbilledAmount = entries.filter((e) => !e.billed && e.amount).reduce((s, e) => s + (e.amount ?? 0), 0);
56
57    return NextResponse.json({
58      entries,
59      totalEntries: entries.length,
60      totalUnbilledHours: Math.round(totalUnbilledHours * 100) / 100,
61      totalUnbilledAmount: Math.round(totalUnbilledAmount * 100) / 100,
62    });
63  } catch (error) {
64    const message = error instanceof Error ? error.message : 'Failed to fetch time entries';
65    return NextResponse.json({ error: message }, { status: 500 });
66  }
67}

1// components/FreshBooksDashboard.tsx
2'use client';
3
4import { useEffect, useState } from 'react';
5
6interface Invoice {
7  id: number;
8  number: string;
9  clientName: string;
10  createDate: string;
11  dueDate: string;
12  total: number;
13  outstanding: number;
14  currency: string;
15  status: number;
16  statusLabel: string;
17  isPaid: boolean;
18}
19
20const STATUS_COLORS: Record<number, string> = {
21  1: 'bg-gray-100 text-gray-600',
22  2: 'bg-blue-100 text-blue-700',
23  4: 'bg-blue-100 text-blue-700',
24  5: 'bg-yellow-100 text-yellow-700',
25  6: 'bg-red-100 text-red-700',
26  8: 'bg-green-100 text-green-700',
27  9: 'bg-green-100 text-green-700',
28};
29
30export default function FreshBooksDashboard() {
31  const [invoices, setInvoices] = useState<Invoice[]>([]);
32  const [unbilledHours, setUnbilledHours] = useState(0);
33  const [unbilledAmount, setUnbilledAmount] = useState(0);
34  const [loading, setLoading] = useState(true);
35  const [statusFilter, setStatusFilter] = useState<number | null>(null);
36  const [error, setError] = useState('');
37
38  useEffect(() => {
39    Promise.all([
40      fetch('/api/freshbooks/invoices').then((r) => r.json()),
41      fetch('/api/freshbooks/time-entries').then((r) => r.json()),
42    ]).then(([invData, timeData]) => {
43      if (invData.error) throw new Error(invData.error);
44      setInvoices(invData.invoices ?? []);
45      setUnbilledHours(timeData.totalUnbilledHours ?? 0);
46      setUnbilledAmount(timeData.totalUnbilledAmount ?? 0);
47    }).catch((e) => setError(e.message)).finally(() => setLoading(false));
48  }, []);
49
50  const totalOutstanding = invoices.filter((i) => !i.isPaid).reduce((s, i) => s + i.outstanding, 0);
51  const overdueCount = invoices.filter((i) => i.status === 6).length;
52
53  const filtered = statusFilter ? invoices.filter((i) => i.status === statusFilter) : invoices;
54
55  if (loading) return <div className="p-8 text-center">Loading FreshBooks data...</div>;
56  if (error) return <div className="p-8 text-red-600">Error: {error}</div>;
57
58  return (
59    <div className="p-6 max-w-5xl mx-auto">
60      <h1 className="text-2xl font-bold mb-6">FreshBooks Dashboard</h1>
61
62      <div className="grid grid-cols-2 md:grid-cols-4 gap-4 mb-8">
63        {[{label: 'Outstanding', value: `$${totalOutstanding.toFixed(2)}`, color: 'text-blue-600'},
64          {label: 'Overdue', value: String(overdueCount), color: 'text-red-600'},
65          {label: 'Unbilled Hours', value: `${unbilledHours}h`, color: 'text-yellow-600'},
66          {label: 'Unbilled Value', value: `$${unbilledAmount.toFixed(2)}`, color: 'text-purple-600'},
67        ].map(({label, value, color}) => (
68          <div key={label} className="border rounded-lg p-4">
69            <p className="text-sm text-gray-500">{label}</p>
70            <p className={`text-xl font-bold ${color}`}>{value}</p>
71          </div>
72        ))}
73      </div>
74
75      <div className="flex gap-2 mb-4 flex-wrap">
76        <button onClick={() => setStatusFilter(null)} className={`px-3 py-1 rounded text-sm ${!statusFilter ? 'bg-blue-600 text-white' : 'bg-gray-100'}`}>All</button>
77        {[{status: 2, label: 'Sent'}, {status: 6, label: 'Overdue'}, {status: 8, label: 'Paid'}, {status: 1, label: 'Draft'}].map(({status, label}) => (
78          <button key={status} onClick={() => setStatusFilter(status)}
79            className={`px-3 py-1 rounded text-sm ${statusFilter === status ? 'bg-blue-600 text-white' : 'bg-gray-100'}`}>{label}</button>
80        ))}
81      </div>
82
83      <div className="overflow-x-auto">
84        <table className="w-full text-sm">
85          <thead>
86            <tr className="border-b">
87              <th className="text-left py-2 font-medium">Invoice #</th>
88              <th className="text-left py-2 font-medium">Client</th>
89              <th className="text-left py-2 font-medium">Date</th>
90              <th className="text-right py-2 font-medium">Amount</th>
91              <th className="text-left py-2 font-medium">Status</th>
92              <th className="text-left py-2 font-medium">View</th>
93            </tr>
94          </thead>
95          <tbody>
96            {filtered.map((inv) => (
97              <tr key={inv.id} className="border-b hover:bg-gray-50">
98                <td className="py-3">{inv.number}</td>
99                <td className="py-3">{inv.clientName}</td>
100                <td className="py-3">{inv.createDate}</td>
101                <td className="py-3 text-right">{inv.currency} {inv.total.toFixed(2)}</td>
102                <td className="py-3">
103                  <span className={`px-2 py-1 rounded-full text-xs ${STATUS_COLORS[inv.status] ?? 'bg-gray-100'}`}>
104                    {inv.statusLabel}
105                  </span>
106                </td>
107                <td className="py-3">
108                  <a href={`https://my.freshbooks.com/#/invoice/${inv.id}`} target="_blank" rel="noopener noreferrer"
109                    className="text-blue-500 hover:underline text-xs">Open →</a>
110                </td>
111              </tr>
112            ))}
113          </tbody>
114        </table>
115      </div>
116    </div>
117  );
118}