@timesheet/plugin-xero 1.0.1

package/README.md

@@ -0,0 +1,41 @@
+# Xero Sync
+
+> Intended integration between Timesheet and Xero. Early scaffold, not yet functional.
+
+This package is an early scaffold. The handlers are wired into the plugin runtime and return placeholder results (for example, `testConnection` reports OK and `syncTaskToExternal` echoes the task id), but no calls are made to the Xero API yet. The manifest below describes the intended shape of the integration rather than working behavior.
+
+- Package: `@timesheet/plugin-xero`
+- Manifest id: `xero-sync`
+- Category: accounting
+- Status: scaffold (no Xero API integration implemented)
+
+## Authentication
+
+OAuth 2.0. Scopes are placeholders (`read`, `write`) and will be replaced with the real Xero scopes when the integration is implemented.
+
+## Configuration
+
+| Option | Required | Default | Description |
+| --- | --- | --- | --- |
+| `syncDirection` | yes | `bidirectional` | One of `bidirectional`, `timesheet-to-external`, `external-to-timesheet`. |
+
+## Mappings
+
+- **Project mapping**: Timesheet project to Xero (placeholder, not yet wired to real Xero entities).
+
+## Triggers
+
+- **Task Created** (event): scaffolded handler for new Timesheet tasks.
+- **Xero Webhook** (webhook): scaffolded inbound endpoint.
+- **Scheduled Full Sync** (daily at 02:00 UTC): scaffolded background sync.
+- **Manual Sync** (user action): scaffolded sync from the integration settings page.
+
+## 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. Shared tests live in `integrations/tests/` and run from the `integrations/` root with `npm test`.

package/dist/handlers/handleWebhook.d.ts

@@ -0,0 +1,5 @@
+import { WebhookInput } from '@timesheet/integration-sdk';
+export declare const handleWebhook: import("@timesheet/integration-sdk").IntegrationHandler<WebhookInput, {
+    system: string;
+    handled: boolean;
+}, Record<string, unknown>>;

package/dist/handlers/handleWebhook.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleWebhook = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const SYSTEM = 'xero';
+exports.handleWebhook = (0, integration_sdk_1.defineHandler)(async (input, context) => {
+    context.logger.info('Handling webhook', {
+        system: SYSTEM,
+        method: input.method,
+        installationId: context.installationId
+    });
+    return {
+        system: SYSTEM,
+        handled: true
+    };
+});

package/dist/handlers/listExternalProjects.d.ts

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

package/dist/handlers/listExternalProjects.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listExternalProjects = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const SYSTEM = 'xero';
+exports.listExternalProjects = (0, integration_sdk_1.defineHandler)(async (_input, context) => {
+    context.logger.info('Listing external projects', {
+        system: SYSTEM,
+        installationId: context.installationId
+    });
+    return [
+        { id: 'xero-project-1', name: 'Xero Sync Project 1' },
+        { id: 'xero-project-2', name: 'Xero Sync Project 2' }
+    ];
+});

package/dist/handlers/runFullSync.d.ts

@@ -0,0 +1,5 @@
+export declare const runFullSync: import("@timesheet/integration-sdk").IntegrationHandler<void, {
+    system: string;
+    status: string;
+    syncedCount: number;
+}, Record<string, unknown>>;

package/dist/handlers/runFullSync.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFullSync = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const SYSTEM = 'xero';
+exports.runFullSync = (0, integration_sdk_1.defineHandler)(async (_input, context) => {
+    context.logger.info('Running full sync', {
+        system: SYSTEM,
+        installationId: context.installationId,
+        syncDirection: context.config?.syncDirection ?? 'bidirectional'
+    });
+    return {
+        system: SYSTEM,
+        status: 'completed',
+        syncedCount: 0
+    };
+});

package/dist/handlers/syncTaskFromExternal.d.ts

@@ -0,0 +1,5 @@
+import { WebhookInput } from '@timesheet/integration-sdk';
+export declare const syncTaskFromExternal: import("@timesheet/integration-sdk").IntegrationHandler<WebhookInput, {
+    system: string;
+    accepted: boolean;
+}, Record<string, unknown>>;

package/dist/handlers/syncTaskFromExternal.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncTaskFromExternal = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const SYSTEM = 'xero';
+exports.syncTaskFromExternal = (0, integration_sdk_1.defineHandler)(async (input, context) => {
+    context.logger.info('Syncing task from external payload', {
+        system: SYSTEM,
+        method: input.method,
+        installationId: context.installationId
+    });
+    return {
+        system: SYSTEM,
+        accepted: true
+    };
+});

package/dist/handlers/syncTaskToExternal.d.ts

@@ -0,0 +1,6 @@
+import { TaskCreatedInput } from '@timesheet/integration-sdk';
+export declare const syncTaskToExternal: import("@timesheet/integration-sdk").IntegrationHandler<TaskCreatedInput, {
+    system: string;
+    taskId: string;
+    direction: string;
+}, Record<string, unknown>>;

package/dist/handlers/syncTaskToExternal.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncTaskToExternal = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const SYSTEM = 'xero';
+exports.syncTaskToExternal = (0, integration_sdk_1.defineHandler)(async (input, context) => {
+    context.logger.info('Syncing task to external system', {
+        system: SYSTEM,
+        taskId: input.taskId,
+        installationId: context.installationId
+    });
+    return {
+        system: SYSTEM,
+        taskId: input.taskId,
+        direction: 'timesheet-to-external'
+    };
+});

package/dist/handlers/testConnection.d.ts

@@ -0,0 +1,5 @@
+export declare const testConnection: import("@timesheet/integration-sdk").IntegrationHandler<void, {
+    system: string;
+    ok: boolean;
+    installationId: string;
+}, Record<string, unknown>>;

package/dist/handlers/testConnection.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testConnection = void 0;
+const integration_sdk_1 = require("@timesheet/integration-sdk");
+const SYSTEM = 'xero';
+exports.testConnection = (0, integration_sdk_1.defineHandler)(async (_input, context) => {
+    context.logger.info('Testing integration connection', {
+        system: SYSTEM,
+        installationId: context.installationId
+    });
+    return {
+        system: SYSTEM,
+        ok: true,
+        installationId: context.installationId
+    };
+});

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { syncTaskToExternal } from './handlers/syncTaskToExternal';
+export { syncTaskFromExternal } from './handlers/syncTaskFromExternal';
+export { handleWebhook } from './handlers/handleWebhook';
+export { runFullSync } from './handlers/runFullSync';
+export { testConnection } from './handlers/testConnection';
+export { listExternalProjects } from './handlers/listExternalProjects';
+export declare const PLUGIN_SYSTEM = "xero";
+export declare const PLUGIN_NAME = "Xero Sync";

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_NAME = exports.PLUGIN_SYSTEM = exports.listExternalProjects = exports.testConnection = exports.runFullSync = exports.handleWebhook = 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 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 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; } });
+exports.PLUGIN_SYSTEM = 'xero';
+exports.PLUGIN_NAME = 'Xero Sync';

package/manifest.json

@@ -0,0 +1,150 @@
+{
+  "id": "xero-sync",
+  "name": "Xero Sync",
+  "version": "1.0.1",
+  "description": "Timesheet Xero Sync plugin integration",
+  "category": "accounting",
+  "tags": ["sync", "timesheet", "xero"],
+  "dataAccess": ["projects", "tasks", "colleagues", "settings"],
+  "externalAuth": [
+    {
+      "id": "xero",
+      "type": "oauth2",
+      "oauth": {
+        "authorizeUrl": "https://example.com/oauth/authorize",
+        "tokenUrl": "https://example.com/oauth/token",
+        "scopes": ["read", "write"]
+      }
+    }
+  ],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "syncDirection": {
+        "type": "string",
+        "title": "Sync Direction",
+        "enum": ["bidirectional", "timesheet-to-external", "external-to-timesheet"],
+        "default": "bidirectional",
+        "x-ui-widget": "radio"
+      }
+    },
+    "required": ["syncDirection"]
+  },
+  "mappingSchema": {
+    "system": "xero",
+    "mappings": [
+      {
+        "id": "projects",
+        "title": "Project Mapping",
+        "description": "Map Timesheet projects to Xero Sync projects",
+        "localEntity": {
+          "type": "project",
+          "label": "Timesheet Project",
+          "display": "{{title}}"
+        },
+        "externalEntity": {
+          "type": "project",
+          "label": "Xero Sync Project",
+          "fetchAction": "list-external-projects"
+        },
+        "required": true,
+        "minMappings": 1
+      }
+    ]
+  },
+  "triggers": [
+    {
+      "id": "task-created",
+      "type": "event",
+      "name": "Task Created",
+      "description": "Sync when a new task is created",
+      "events": ["task.create"],
+      "configurable": true
+    },
+    {
+      "id": "integration-webhook",
+      "type": "webhook",
+      "name": "Xero Sync Webhook",
+      "description": "Receive inbound changes from Xero Sync",
+      "configurable": false,
+      "webhook": {
+        "signature": {
+          "header": "x-timesheet-signature",
+          "algorithm": "hmac-sha256",
+          "secretConfigKey": "webhookSecret"
+        }
+      }
+    },
+    {
+      "id": "full-sync",
+      "type": "schedule",
+      "name": "Scheduled Full Sync",
+      "description": "Run background synchronization",
+      "schedule": "0 2 * * *",
+      "timezone": "UTC",
+      "configurable": true
+    },
+    {
+      "id": "manual-sync",
+      "type": "user_action",
+      "name": "Manual Sync",
+      "description": "Trigger a sync from settings",
+      "userAction": {
+        "label": "Sync Now",
+        "placement": "settings"
+      }
+    }
+  ],
+  "actions": [
+    {
+      "id": "sync-task-to-external",
+      "name": "Sync task to Xero Sync",
+      "handler": "syncTaskToExternal"
+    },
+    {
+      "id": "sync-task-from-external",
+      "name": "Sync task from Xero Sync",
+      "handler": "syncTaskFromExternal"
+    },
+    {
+      "id": "handle-webhook",
+      "handler": "handleWebhook",
+      "internal": true
+    },
+    {
+      "id": "run-full-sync",
+      "name": "Run full sync",
+      "handler": "runFullSync"
+    },
+    {
+      "id": "test-connection",
+      "name": "Test connection",
+      "handler": "testConnection"
+    },
+    {
+      "id": "list-external-projects",
+      "handler": "listExternalProjects",
+      "internal": true
+    }
+  ],
+  "pages": [
+    {
+      "id": "dashboard",
+      "title": "Sync Dashboard",
+      "icon": "chart-bar",
+      "layout": "dashboard",
+      "widgets": [
+        {
+          "id": "manual-sync-btn",
+          "type": "action_button",
+          "title": "Manual Sync",
+          "config": {
+            "actionId": "run-full-sync",
+            "label": "Run Full Sync",
+            "variant": "primary"
+          }
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@timesheet/plugin-xero",
+  "version": "1.0.1",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "manifest.json"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@timesheet/integration-sdk": "^0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.9.3"
+  }
+}