@timesheet/plugin-freshbooks 1.0.0

package/dist/lib/freshbooksClient.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FreshBooksClient = void 0;
+class FreshBooksClient {
+    constructor(options) {
+        this.cachedToken = null;
+        this.resolvedBusiness = null;
+        // FreshBooks time entries reference a client, but only the project carries
+        // the client relationship — cache project → client so outbound pushes don't
+        // refetch the project on every task.
+        this.projectClientCache = new Map();
+        this.fetchAccessToken = options.getAccessToken;
+        this.fetchRefreshedToken = options.refreshAccessToken;
+        this.businessIdOverride = options.businessId;
+    }
+    // The access token is not scoped to a business; `/users/me` lists every
+    // business the identity belongs to. Time Tracking, Projects, Services and
+    // Team Members are keyed on `business.id`; Events (webhooks) on `account_id`.
+    async resolveBusiness() {
+        if (this.resolvedBusiness) {
+            return this.resolvedBusiness;
+        }
+        const me = await this.request('GET', '/auth/api/v1/users/me');
+        const businesses = (me?.response?.business_memberships ?? [])
+            .map((membership) => membership.business)
+            .filter((business) => !!business?.id && !!business.account_id);
+        if (businesses.length === 0) {
+            throw new Error('FreshBooks: the connected identity has no business membership.');
+        }
+        let chosen = businesses[0];
+        if (this.businessIdOverride) {
+            const match = businesses.find((business) => String(business.id) === this.businessIdOverride);
+            if (match) {
+                chosen = match;
+            }
+        }
+        this.resolvedBusiness = chosen;
+        return chosen;
+    }
+    async businessId() {
+        return String((await this.resolveBusiness()).id);
+    }
+    async accountId() {
+        return (await this.resolveBusiness()).account_id;
+    }
+    async testConnection() {
+        const business = await this.resolveBusiness();
+        return !!business?.id;
+    }
+    async listProjects() {
+        const bid = await this.businessId();
+        const projects = await this.paginate(`/projects/business/${encodeURIComponent(bid)}/projects`, 'projects', { active: 'true' });
+        return projects.map((project) => {
+            if (project.id && typeof project.client_id === 'number') {
+                this.projectClientCache.set(project.id, project.client_id);
+            }
+            return {
+                id: String(project.id),
+                name: project.title ?? String(project.id),
+                clientId: typeof project.client_id === 'number' ? project.client_id : null,
+                active: project.active ?? true
+            };
+        });
+    }
+    async getProject(projectId) {
+        const bid = await this.businessId();
+        try {
+            const response = await this.request('GET', `/projects/business/${encodeURIComponent(bid)}/projects/${encodeURIComponent(projectId)}`);
+            return response?.project ?? null;
+        }
+        catch (err) {
+            if (String(err).includes('(404)')) {
+                return null;
+            }
+            throw err;
+        }
+    }
+    // The FreshBooks time entry needs the client id; only the project knows it.
+    async resolveClientId(projectId) {
+        const numericId = Number(projectId);
+        if (Number.isFinite(numericId) && this.projectClientCache.has(numericId)) {
+            return this.projectClientCache.get(numericId) ?? null;
+        }
+        const project = await this.getProject(projectId);
+        if (project?.id && typeof project.client_id === 'number') {
+            this.projectClientCache.set(project.id, project.client_id);
+            return project.client_id;
+        }
+        return null;
+    }
+    async listTeamMembers() {
+        const bid = await this.businessId();
+        const members = await this.paginateResponseArray(`/auth/api/v1/businesses/${encodeURIComponent(bid)}/team_members`);
+        return members
+            .filter((member) => member.identity_id != null)
+            .map((member) => ({
+            id: String(member.identity_id),
+            name: [member.first_name, member.last_name].filter(Boolean).join(' ').trim() ||
+                member.email ||
+                String(member.identity_id),
+            active: member.active ?? true
+        }));
+    }
+    async listServices() {
+        const bid = await this.businessId();
+        const services = await this.paginate(`/comments/business/${encodeURIComponent(bid)}/services`, 'services', {});
+        return services
+            .filter((service) => (service.vis_state ?? 0) === 0)
+            .map((service) => ({
+            id: String(service.id),
+            name: service.name ?? String(service.id),
+            billable: service.billable ?? true
+        }));
+    }
+    async listTimeEntries(options) {
+        const bid = await this.businessId();
+        const query = {};
+        if (options?.updatedSinceIso) {
+            query.updated_since = options.updatedSinceIso;
+        }
+        return this.paginate(`/timetracking/business/${encodeURIComponent(bid)}/time_entries`, 'time_entries', query);
+    }
+    async getTimeEntry(id) {
+        const bid = await this.businessId();
+        try {
+            const response = await this.request('GET', `/timetracking/business/${encodeURIComponent(bid)}/time_entries/${encodeURIComponent(id)}`);
+            return response?.time_entry ?? null;
+        }
+        catch (err) {
+            if (String(err).includes('(404)')) {
+                return null;
+            }
+            throw err;
+        }
+    }
+    async createTimeEntry(payload) {
+        const bid = await this.businessId();
+        const response = await this.request('POST', `/timetracking/business/${encodeURIComponent(bid)}/time_entries`, undefined, { time_entry: payload });
+        if (!response?.time_entry?.id) {
+            throw new Error('FreshBooks createTimeEntry did not return a time entry id.');
+        }
+        return response.time_entry;
+    }
+    async updateTimeEntry(id, payload) {
+        const bid = await this.businessId();
+        const response = await this.request('PUT', `/timetracking/business/${encodeURIComponent(bid)}/time_entries/${encodeURIComponent(id)}`, undefined, { time_entry: payload });
+        if (!response?.time_entry?.id) {
+            throw new Error('FreshBooks updateTimeEntry did not return a time entry id.');
+        }
+        return response.time_entry;
+    }
+    async deleteTimeEntry(id) {
+        const bid = await this.businessId();
+        await this.request('DELETE', `/timetracking/business/${encodeURIComponent(bid)}/time_entries/${encodeURIComponent(id)}`);
+    }
+    // ---- Webhook callbacks (Events API, keyed on account_id) ----
+    async listCallbacks() {
+        const aid = await this.accountId();
+        const response = await this.request('GET', `/events/account/${encodeURIComponent(aid)}/events/callbacks`);
+        return response?.response?.result?.callbacks ?? [];
+    }
+    async createCallback(event, uri) {
+        const aid = await this.accountId();
+        const response = await this.request('POST', `/events/account/${encodeURIComponent(aid)}/events/callbacks`, undefined, { callback: { event, uri } });
+        return response?.response?.result?.callback ?? null;
+    }
+    // Confirm ownership of a freshly created callback by echoing back the
+    // verifier FreshBooks delivered to the callback URL.
+    async verifyCallback(callbackId, verifier) {
+        const aid = await this.accountId();
+        await this.request('PUT', `/events/account/${encodeURIComponent(aid)}/events/callbacks/${encodeURIComponent(callbackId)}`, undefined, { callback: { verifier } });
+    }
+    async deleteCallback(callbackId) {
+        const aid = await this.accountId();
+        await this.request('DELETE', `/events/account/${encodeURIComponent(aid)}/events/callbacks/${encodeURIComponent(callbackId)}`);
+    }
+    // ---- Internals ----
+    async paginate(path, key, baseQuery) {
+        const out = [];
+        let page = 1;
+        while (true) {
+            const response = await this.request('GET', path, {
+                ...baseQuery,
+                page: String(page),
+                per_page: String(FreshBooksClient.PAGE_SIZE)
+            });
+            const items = Array.isArray(response?.[key]) ? response[key] : [];
+            out.push(...items);
+            const meta = response?.meta;
+            const pages = meta?.pages ?? 1;
+            if (page >= pages || items.length === 0) {
+                break;
+            }
+            page += 1;
+        }
+        return out;
+    }
+    // The Identity/Auth API returns list payloads under `response` (an array)
+    // rather than a named resource key.
+    async paginateResponseArray(path) {
+        const out = [];
+        let page = 1;
+        while (true) {
+            const response = await this.request('GET', path, {
+                page: String(page),
+                per_page: String(FreshBooksClient.PAGE_SIZE)
+            });
+            const items = Array.isArray(response?.response) ? response.response : [];
+            out.push(...items);
+            const pages = response?.meta?.pages ?? 1;
+            if (page >= pages || items.length === 0) {
+                break;
+            }
+            page += 1;
+        }
+        return out;
+    }
+    async getAccessToken() {
+        if (this.cachedToken) {
+            return this.cachedToken;
+        }
+        this.cachedToken = await this.fetchAccessToken();
+        return this.cachedToken;
+    }
+    async refreshAccessToken() {
+        this.cachedToken = null;
+        this.cachedToken = await this.fetchRefreshedToken();
+        return this.cachedToken;
+    }
+    async request(method, path, query, body, retried = false) {
+        const token = await this.getAccessToken();
+        const url = this.buildUrl(path, query);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), FreshBooksClient.REQUEST_TIMEOUT_MS);
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: 'application/json',
+                    'Content-Type': 'application/json',
+                    // Required by the Projects and Time Tracking (alpha) endpoints.
+                    'Api-Version': 'alpha'
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal
+            });
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                throw new Error(`FreshBooks API ${method} ${path} timed out after ${FreshBooksClient.REQUEST_TIMEOUT_MS}ms`);
+            }
+            throw error;
+        }
+        clearTimeout(timeoutId);
+        if (response.status === 401 && !retried) {
+            const refreshed = await this.refreshAccessToken();
+            if (refreshed) {
+                return this.request(method, path, query, body, true);
+            }
+        }
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw new Error(`FreshBooks API ${method} ${path} failed (${response.status}): ${errorBody}`);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        return (await response.json());
+    }
+    buildUrl(path, query) {
+        const url = new URL(`${FreshBooksClient.BASE_URL}${path}`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value === undefined || value === null || value === '') {
+                    continue;
+                }
+                url.searchParams.append(key, String(value));
+            }
+        }
+        return url.toString();
+    }
+}
+exports.FreshBooksClient = FreshBooksClient;
+FreshBooksClient.BASE_URL = 'https://api.freshbooks.com';
+FreshBooksClient.REQUEST_TIMEOUT_MS = 30000;
+FreshBooksClient.PAGE_SIZE = 100;

package/dist/lib/taskSync.d.ts

@@ -0,0 +1,22 @@
+import { IntegrationContext, MappingRecord } from '@timesheet/integration-sdk';
+import { FreshBooksClient } from './freshbooksClient';
+import { FreshBooksConfig, SyncInput } from './types';
+export interface FreshBooksSyncResult {
+    system: string;
+    status: string;
+    syncedCount: number;
+    details?: Record<string, unknown>;
+}
+export interface SyncBatchCaches {
+    projectMappingByLocalId?: Map<string, MappingRecord>;
+    userMappingByLocalId?: Map<string, MappingRecord>;
+    taskMappingByLocalId?: Map<string, MappingRecord>;
+    rateMappingByLocalId?: Map<string, MappingRecord>;
+}
+export declare function resetSharedClient(): void;
+export declare function createFreshBooksClient(context: IntegrationContext<FreshBooksConfig>): FreshBooksClient;
+export declare function syncTaskToFreshBooks(input: SyncInput, context: IntegrationContext<FreshBooksConfig>, caches?: SyncBatchCaches): Promise<FreshBooksSyncResult>;
+export declare function runFreshBooksFullSync(context: IntegrationContext<FreshBooksConfig>): Promise<FreshBooksSyncResult>;
+export declare function handleFreshBooksWebhook(input: SyncInput, context: IntegrationContext<FreshBooksConfig>): Promise<FreshBooksSyncResult>;
+export declare function syncTaskFromFreshBooks(input: SyncInput, context: IntegrationContext<FreshBooksConfig>): Promise<FreshBooksSyncResult>;
+export declare function registerFreshBooksWebhooks(context: IntegrationContext<FreshBooksConfig>): Promise<FreshBooksSyncResult>;