@timesheet/plugin-freshbooks 1.0.0

package/README.md

@@ -0,0 +1,59 @@
+# FreshBooks Sync
+
+> Synchronize Timesheet tasks with FreshBooks time entries.
+
+Bidirectional synchronization between Timesheet tasks and FreshBooks `time_entries`. Timesheet projects map to FreshBooks projects and Timesheet users map to FreshBooks team members, so logged time lands on the right project and teammate in FreshBooks for billing.
+
+- Package: `@timesheet/plugin-freshbooks`
+- Manifest id: `freshbooks-sync`
+- Category: accounting
+
+## Authentication
+
+OAuth 2.0 against FreshBooks. The access token is not scoped to a single business, so the plugin resolves the target business from `GET /auth/api/v1/users/me`:
+
+- `business.id` keys the Time Tracking, Projects, Services and Team Members endpoints.
+- `business.account_id` keys the Events (webhook callback) endpoints.
+
+When the connected identity belongs to more than one business, set the `businessId` config option to pick one; otherwise the first membership is used.
+
+Requested scopes: `user:profile:read`, `user:time_entries:read`, `user:time_entries:write`, `user:projects:read`, `user:clients:read`, `user:billable_items:read`, `user:teams:read`.
+
+## Configuration
+
+| Option | Required | Default | Description |
+| --- | --- | --- | --- |
+| `syncDirection` | yes | `bidirectional` | One of `bidirectional`, `timesheet-to-freshbooks`, `freshbooks-to-timesheet`. |
+| `businessId` | no | (first) | FreshBooks `business.id` to sync when the account has multiple businesses. |
+
+## Mappings
+
+- **Project mapping** (required): Timesheet project to FreshBooks project. The FreshBooks project supplies the client the time entry is billed to.
+- **User mapping** (required): Timesheet user to FreshBooks team member (`identity_id`).
+- **Rate mapping** (optional): Timesheet rate to FreshBooks service (`service_id`).
+
+## Triggers
+
+- **Task Changed** (event): pushes Timesheet task create, update, and delete events to FreshBooks.
+- **FreshBooks Webhook** (webhook): receives inbound `time_entry` changes.
+- **Scheduled Full Sync** (daily at 02:00 UTC): reconciles task changes to FreshBooks.
+- **Manual Sync** (user action): pulls FreshBooks time entries updated since the last run.
+- **Register Webhooks** (user action): registers the FreshBooks callback for real-time inbound sync.
+
+### Webhook
+
+FreshBooks callbacks are registered per account. **Register Webhooks** creates a single `time_entry` callback pointing at the plugin's webhook endpoint. FreshBooks then delivers a verification `verifier` to that endpoint; the handler stores it (it becomes the HMAC secret) and confirms the callback. Subsequent deliveries are authenticated with the `X-FreshBooks-Hmac-SHA256` signature over the raw body. The Scheduled Full Sync and Manual Sync remain the reliable inbound path if callbacks are not registered.
+
+### Echo suppression
+
+FreshBooks time entries expose no `updated_at`, only a `created_at` and an `updated_since` list filter. Outbound echoes are skipped with the SDK's `isAlreadySyncedLocalChange` guard; inbound echoes are detected by comparing the incoming entry's content to the local task (`taskDiffersFromDesired`) and re-stamping `timesheetUpdatedAt` after each inbound write.
+
+## Development
+
+```bash
+npm install        # or: npm ci
+npm run build      # compile TypeScript into dist/
+npm run typecheck
+```
+
+The package ships `dist/` and `manifest.json`; the sandboxed plugin runtime loads it by package name, version, and integrity (`sha512-...`). Shared tests live in `integrations/tests/` and run from the `integrations/` root with `npm test`.

package/dist/handlers/handleSyncBatch.d.ts

@@ -0,0 +1,4 @@
+import { SyncModeInput } from '@timesheet/integration-sdk';
+import { FreshBooksConfig } from '../lib/types';
+import { FreshBooksSyncResult } from '../lib/taskSync';
+export declare const handleSyncBatch: import("@timesheet/integration-sdk").IntegrationHandler<SyncModeInput, FreshBooksSyncResult, FreshBooksConfig>;

package/dist/handlers/handleSyncBatch.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleSyncBatch = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const taskSync_1 = require("../lib/taskSync");
+const SYSTEM = 'freshbooks';
+const PROJECT_ENTITY = 'project';
+const USER_ENTITY = 'user';
+const TASK_ENTITY = 'task';
+const RATE_ENTITY = 'rate';
+exports.handleSyncBatch = (0, integration_sdk_1.defineHandler)(async (input, context) => {
+    context.logger.info('Processing sync batch', {
+        sinceVersion: input.sinceVersion,
+        headVersion: input.headVersion,
+        changeCount: input.changes.length,
+        hasMore: input.hasMore
+    });
+    const [projectMappings, userMappings, taskMappings, rateMappings] = await Promise.all([
+        context.mappings.list({ system: SYSTEM, entity: PROJECT_ENTITY }),
+        context.mappings.list({ system: SYSTEM, entity: USER_ENTITY }),
+        context.mappings.list({ system: SYSTEM, entity: TASK_ENTITY }),
+        context.mappings.list({ system: SYSTEM, entity: RATE_ENTITY })
+    ]);
+    const projectMappingByLocalId = new Map();
+    for (const mapping of projectMappings) {
+        projectMappingByLocalId.set(mapping.localId, mapping);
+    }
+    const userMappingByLocalId = new Map();
+    for (const mapping of userMappings) {
+        userMappingByLocalId.set(mapping.localId, mapping);
+    }
+    const taskMappingByLocalId = new Map();
+    for (const mapping of taskMappings) {
+        taskMappingByLocalId.set(mapping.localId, mapping);
+    }
+    const rateMappingByLocalId = new Map();
+    for (const mapping of rateMappings) {
+        rateMappingByLocalId.set(mapping.localId, mapping);
+    }
+    let syncedCount = 0;
+    const errors = [];
+    for (const change of input.changes) {
+        if (change.entityType !== 'task') {
+            continue;
+        }
+        try {
+            const event = change.op === 'DELETE' ? 'task.delete' : 'task.update';
+            const item = change.item;
+            const result = await (0, taskSync_1.syncTaskToFreshBooks)({
+                event,
+                taskId: change.entityId,
+                item
+            }, context, { projectMappingByLocalId, userMappingByLocalId, taskMappingByLocalId, rateMappingByLocalId });
+            if (result.status === 'synced' || result.status === 'deleted') {
+                syncedCount++;
+            }
+            else if (result.status === 'skipped') {
+                context.logger.debug('Change skipped', { entityId: change.entityId, reason: result.details?.reason });
+            }
+        }
+        catch (err) {
+            context.logger.error('Failed to sync change', {
+                entityId: change.entityId,
+                op: change.op,
+                error: String(err)
+            });
+            errors.push({ entityId: change.entityId, error: String(err) });
+        }
+    }
+    return {
+        system: SYSTEM,
+        status: errors.length > 0 ? 'partial' : 'completed',
+        syncedCount,
+        details: {
+            sinceVersion: input.sinceVersion,
+            headVersion: input.headVersion,
+            totalChanges: input.changes.length,
+            hasMore: input.hasMore,
+            errors: errors.length > 0 ? errors : undefined
+        }
+    };
+});

package/dist/handlers/handleWebhook.d.ts

@@ -0,0 +1,3 @@
+import { FreshBooksConfig, SyncInput } from '../lib/types';
+import { FreshBooksSyncResult } from '../lib/taskSync';
+export declare const handleWebhook: import("@timesheet/integration-sdk").IntegrationHandler<SyncInput, FreshBooksSyncResult, FreshBooksConfig>;

package/dist/handlers/handleWebhook.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleWebhook = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const taskSync_1 = require("../lib/taskSync");
+exports.handleWebhook = (0, integration_sdk_1.defineHandler)(async (input, context) => {
+    context.logger.info('Handling FreshBooks webhook', {
+        installationId: context.installationId,
+        hasBody: !!input?.body
+    });
+    return await (0, taskSync_1.handleFreshBooksWebhook)(input, context);
+});

package/dist/handlers/listExternalProjects.d.ts

@@ -0,0 +1,3 @@
+import { ExternalEntity } from '@timesheet/integration-sdk';
+import { FreshBooksConfig } from '../lib/types';
+export declare const listExternalProjects: import("@timesheet/integration-sdk").IntegrationHandler<void, ExternalEntity[], FreshBooksConfig>;

package/dist/handlers/listExternalProjects.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listExternalProjects = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const taskSync_1 = require("../lib/taskSync");
+const SYSTEM = 'freshbooks';
+exports.listExternalProjects = (0, integration_sdk_1.defineHandler)(async (_input, context) => {
+    context.logger.info('Listing FreshBooks projects', {
+        system: SYSTEM,
+        installationId: context.installationId
+    });
+    const client = (0, taskSync_1.createFreshBooksClient)(context);
+    return await client.listProjects();
+});

package/dist/handlers/listExternalServices.d.ts

@@ -0,0 +1,3 @@
+import { ExternalEntity } from '@timesheet/integration-sdk';
+import { FreshBooksConfig } from '../lib/types';
+export declare const listExternalServices: import("@timesheet/integration-sdk").IntegrationHandler<void, ExternalEntity[], FreshBooksConfig>;

package/dist/handlers/listExternalServices.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listExternalServices = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const taskSync_1 = require("../lib/taskSync");
+const SYSTEM = 'freshbooks';
+exports.listExternalServices = (0, integration_sdk_1.defineHandler)(async (_input, context) => {
+    context.logger.info('Listing FreshBooks services', {
+        system: SYSTEM,
+        installationId: context.installationId
+    });
+    const client = (0, taskSync_1.createFreshBooksClient)(context);
+    return await client.listServices();
+});

package/dist/handlers/listExternalUsers.d.ts

@@ -0,0 +1,3 @@
+import { ExternalEntity } from '@timesheet/integration-sdk';
+import { FreshBooksConfig } from '../lib/types';
+export declare const listExternalUsers: import("@timesheet/integration-sdk").IntegrationHandler<void, ExternalEntity[], FreshBooksConfig>;

package/dist/handlers/listExternalUsers.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listExternalUsers = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const taskSync_1 = require("../lib/taskSync");
+const SYSTEM = 'freshbooks';
+exports.listExternalUsers = (0, integration_sdk_1.defineHandler)(async (_input, context) => {
+    context.logger.info('Listing FreshBooks team members', {
+        system: SYSTEM,
+        installationId: context.installationId
+    });
+    const client = (0, taskSync_1.createFreshBooksClient)(context);
+    return await client.listTeamMembers();
+});

package/dist/handlers/registerWebhooks.d.ts

@@ -0,0 +1,3 @@
+import { FreshBooksConfig } from '../lib/types';
+import { FreshBooksSyncResult } from '../lib/taskSync';
+export declare const registerWebhooks: import("@timesheet/integration-sdk").IntegrationHandler<void, FreshBooksSyncResult, FreshBooksConfig>;

package/dist/handlers/registerWebhooks.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWebhooks = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const taskSync_1 = require("../lib/taskSync");
+exports.registerWebhooks = (0, integration_sdk_1.defineHandler)(async (_input, context) => {
+    context.logger.info('Registering FreshBooks webhooks', {
+        installationId: context.installationId
+    });
+    return await (0, taskSync_1.registerFreshBooksWebhooks)(context);
+});

package/dist/handlers/runFullSync.d.ts

@@ -0,0 +1,3 @@
+import { FreshBooksConfig } from '../lib/types';
+import { FreshBooksSyncResult } from '../lib/taskSync';
+export declare const runFullSync: import("@timesheet/integration-sdk").IntegrationHandler<void, FreshBooksSyncResult, FreshBooksConfig>;

package/dist/handlers/runFullSync.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFullSync = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const taskSync_1 = require("../lib/taskSync");
+exports.runFullSync = (0, integration_sdk_1.defineHandler)(async (_input, context) => {
+    context.logger.info('Running FreshBooks full sync', {
+        installationId: context.installationId,
+        syncDirection: context.config?.syncDirection ?? 'bidirectional'
+    });
+    return await (0, taskSync_1.runFreshBooksFullSync)(context);
+});

package/dist/handlers/syncTaskFromExternal.d.ts

@@ -0,0 +1,3 @@
+import { FreshBooksConfig, SyncInput } from '../lib/types';
+import { FreshBooksSyncResult } from '../lib/taskSync';
+export declare const syncTaskFromExternal: import("@timesheet/integration-sdk").IntegrationHandler<SyncInput, FreshBooksSyncResult, FreshBooksConfig>;

package/dist/handlers/syncTaskFromExternal.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncTaskFromExternal = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const taskSync_1 = require("../lib/taskSync");
+exports.syncTaskFromExternal = (0, integration_sdk_1.defineHandler)(async (input, context) => {
+    context.logger.info('Syncing task from FreshBooks payload', {
+        installationId: context.installationId,
+        externalTaskId: input?.externalTaskId
+    });
+    return await (0, taskSync_1.syncTaskFromFreshBooks)(input, context);
+});

package/dist/handlers/syncTaskToExternal.d.ts

@@ -0,0 +1,3 @@
+import { FreshBooksConfig, SyncInput } from '../lib/types';
+import { FreshBooksSyncResult } from '../lib/taskSync';
+export declare const syncTaskToExternal: import("@timesheet/integration-sdk").IntegrationHandler<SyncInput, FreshBooksSyncResult, FreshBooksConfig>;

package/dist/handlers/syncTaskToExternal.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncTaskToExternal = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const taskSync_1 = require("../lib/taskSync");
+exports.syncTaskToExternal = (0, integration_sdk_1.defineHandler)(async (input, context) => {
+    context.logger.info('Syncing task to FreshBooks', {
+        installationId: context.installationId,
+        event: input?.event,
+        taskId: input?.taskId ?? input?.item?.id
+    });
+    return await (0, taskSync_1.syncTaskToFreshBooks)(input, context);
+});

package/dist/handlers/testConnection.d.ts

@@ -0,0 +1,7 @@
+import { FreshBooksConfig } from '../lib/types';
+export declare const testConnection: import("@timesheet/integration-sdk").IntegrationHandler<void, {
+    system: string;
+    ok: boolean;
+    installationId: string;
+    businessId: string;
+}, FreshBooksConfig>;

package/dist/handlers/testConnection.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testConnection = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const taskSync_1 = require("../lib/taskSync");
+const SYSTEM = 'freshbooks';
+exports.testConnection = (0, integration_sdk_1.defineHandler)(async (_input, context) => {
+    const client = (0, taskSync_1.createFreshBooksClient)(context);
+    try {
+        const business = await client.resolveBusiness();
+        return {
+            system: SYSTEM,
+            ok: !!business?.id,
+            installationId: context.installationId,
+            businessId: business?.id ? String(business.id) : ''
+        };
+    }
+    catch (err) {
+        context.logger.warn('FreshBooks test connection failed', { error: String(err) });
+        return {
+            system: SYSTEM,
+            ok: false,
+            installationId: context.installationId,
+            businessId: ''
+        };
+    }
+});

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { syncTaskToExternal } from './handlers/syncTaskToExternal';
+export { syncTaskFromExternal } from './handlers/syncTaskFromExternal';
+export { handleSyncBatch } from './handlers/handleSyncBatch';
+export { handleWebhook } from './handlers/handleWebhook';
+export { runFullSync } from './handlers/runFullSync';
+export { registerWebhooks } from './handlers/registerWebhooks';
+export { testConnection } from './handlers/testConnection';
+export { listExternalProjects } from './handlers/listExternalProjects';
+export { listExternalUsers } from './handlers/listExternalUsers';
+export { listExternalServices } from './handlers/listExternalServices';
+export declare const PLUGIN_SYSTEM = "freshbooks";
+export declare const PLUGIN_NAME = "FreshBooks Sync";

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_NAME = exports.PLUGIN_SYSTEM = exports.listExternalServices = exports.listExternalUsers = exports.listExternalProjects = exports.testConnection = exports.registerWebhooks = exports.runFullSync = exports.handleWebhook = exports.handleSyncBatch = exports.syncTaskFromExternal = exports.syncTaskToExternal = void 0;
+var syncTaskToExternal_1 = require("./handlers/syncTaskToExternal");
+Object.defineProperty(exports, "syncTaskToExternal", { enumerable: true, get: function () { return syncTaskToExternal_1.syncTaskToExternal; } });
+var syncTaskFromExternal_1 = require("./handlers/syncTaskFromExternal");
+Object.defineProperty(exports, "syncTaskFromExternal", { enumerable: true, get: function () { return syncTaskFromExternal_1.syncTaskFromExternal; } });
+var handleSyncBatch_1 = require("./handlers/handleSyncBatch");
+Object.defineProperty(exports, "handleSyncBatch", { enumerable: true, get: function () { return handleSyncBatch_1.handleSyncBatch; } });
+var handleWebhook_1 = require("./handlers/handleWebhook");
+Object.defineProperty(exports, "handleWebhook", { enumerable: true, get: function () { return handleWebhook_1.handleWebhook; } });
+var runFullSync_1 = require("./handlers/runFullSync");
+Object.defineProperty(exports, "runFullSync", { enumerable: true, get: function () { return runFullSync_1.runFullSync; } });
+var registerWebhooks_1 = require("./handlers/registerWebhooks");
+Object.defineProperty(exports, "registerWebhooks", { enumerable: true, get: function () { return registerWebhooks_1.registerWebhooks; } });
+var testConnection_1 = require("./handlers/testConnection");
+Object.defineProperty(exports, "testConnection", { enumerable: true, get: function () { return testConnection_1.testConnection; } });
+var listExternalProjects_1 = require("./handlers/listExternalProjects");
+Object.defineProperty(exports, "listExternalProjects", { enumerable: true, get: function () { return listExternalProjects_1.listExternalProjects; } });
+var listExternalUsers_1 = require("./handlers/listExternalUsers");
+Object.defineProperty(exports, "listExternalUsers", { enumerable: true, get: function () { return listExternalUsers_1.listExternalUsers; } });
+var listExternalServices_1 = require("./handlers/listExternalServices");
+Object.defineProperty(exports, "listExternalServices", { enumerable: true, get: function () { return listExternalServices_1.listExternalServices; } });
+exports.PLUGIN_SYSTEM = 'freshbooks';
+exports.PLUGIN_NAME = 'FreshBooks Sync';

package/dist/lib/freshbooksClient.d.ts

@@ -0,0 +1,47 @@
+import { ExternalEntity } from '@timesheet/integration-sdk';
+import { FreshBooksBusiness, FreshBooksCallback, FreshBooksProject, FreshBooksTimeEntry } from './types';
+interface FreshBooksClientOptions {
+    getAccessToken: () => Promise<string>;
+    refreshAccessToken: () => Promise<string>;
+    /** Optional `business.id` override for multi-business identities. */
+    businessId?: string;
+}
+export declare class FreshBooksClient {
+    private static readonly BASE_URL;
+    private static readonly REQUEST_TIMEOUT_MS;
+    private static readonly PAGE_SIZE;
+    private readonly fetchAccessToken;
+    private readonly fetchRefreshedToken;
+    private readonly businessIdOverride;
+    private cachedToken;
+    private resolvedBusiness;
+    private readonly projectClientCache;
+    constructor(options: FreshBooksClientOptions);
+    resolveBusiness(): Promise<FreshBooksBusiness>;
+    businessId(): Promise<string>;
+    accountId(): Promise<string>;
+    testConnection(): Promise<boolean>;
+    listProjects(): Promise<ExternalEntity[]>;
+    getProject(projectId: string): Promise<FreshBooksProject | null>;
+    resolveClientId(projectId: string): Promise<number | null>;
+    listTeamMembers(): Promise<ExternalEntity[]>;
+    listServices(): Promise<ExternalEntity[]>;
+    listTimeEntries(options?: {
+        updatedSinceIso?: string;
+    }): Promise<FreshBooksTimeEntry[]>;
+    getTimeEntry(id: string): Promise<FreshBooksTimeEntry | null>;
+    createTimeEntry(payload: Record<string, unknown>): Promise<FreshBooksTimeEntry>;
+    updateTimeEntry(id: string, payload: Record<string, unknown>): Promise<FreshBooksTimeEntry>;
+    deleteTimeEntry(id: string): Promise<void>;
+    listCallbacks(): Promise<FreshBooksCallback[]>;
+    createCallback(event: string, uri: string): Promise<FreshBooksCallback | null>;
+    verifyCallback(callbackId: string, verifier: string): Promise<void>;
+    deleteCallback(callbackId: string): Promise<void>;
+    private paginate;
+    private paginateResponseArray;
+    private getAccessToken;
+    private refreshAccessToken;
+    private request;
+    private buildUrl;
+}
+export {};