[BE-41] Xero accounting integration

[yusuftomilola]

Overview

Hub accountants use Xero for bookkeeping. Manually re-entering every invoice and payment into Xero is time-consuming and error-prone. Auto-syncing ManageHub invoices and payments to Xero eliminates this.

Context

• InvoicesModule: backend/src/invoices/ — source of invoice data
• PaymentsModule: backend/src/payments/ — source of payment data
• Package: xero-node (Xero's official Node.js SDK)
• @nestjs/schedule: for nightly reconciliation cron job

Tasks

• Create XeroConnection entity: id, hubId (singleton — one per hub), accessToken (encrypted), refreshToken (encrypted), tenantId, connectedAt, expiresAt
• GET /integrations/xero/connect — initiate Xero OAuth 2.0 PKCE flow (admin only)
• GET /integrations/xero/callback — exchange code for tokens; store in XeroConnection
• DELETE /integrations/xero — disconnect and delete XeroConnection (admin only)
• GET /integrations/xero/status — returns connection status (admin only)
• On invoice PAID event: create a matching Xero Invoice via Xero Accounting API
• On payment SUCCESS event: create a Xero Payment record linked to the Xero Invoice
• Nightly @Cron('0 4 * * *') reconciliation job: sync last 24 hours of invoices/payments; log discrepancies
• Token refresh handled automatically before each API call

Files to Modify / Create

• New: backend/src/integrations/xero/ (module, entity, controller, service)
• backend/src/app.module.ts

[sudo-robi]

@sudo-robi has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi maintainer I'm a full stack developer and smart contract developer let me help you resolve this issue and I assure you it will be thoroughly done neatly as I have seen my way around the issue.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @sudo-robi to this issue.

[Uyoxy]

@Uyoxy has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

can i work on this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Uyoxy to this issue.

[sudo-robi]

Hi @yusuftomilola you haven't assigned me

[grantfox-oss]

🦊 GrantFox — @Uyoxy has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #1228)
2. Your PR will be reviewed by the DistinctCodes maintainers

Good luck! Track your progress on GrantFox.

[drips-wave]

Congratulations, @Uyoxy! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Uyoxy: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊