78 lines
2.8 KiB
Markdown
78 lines
2.8 KiB
Markdown
# OpenSpec Change: enterprise-api-plugin-vatdash-bridge
|
|
|
|
- **Change ID**: enterprise-api-plugin-vatdash-bridge
|
|
- **Package**: `@suaveplan/api-plugin-vatdash-bridge`
|
|
- **Category**: api/logistics
|
|
- **Target path**: `api/logistics/api-plugin-vatdash-bridge`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-vatdash-bridge.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/api-plugin-vatdash-bridge` on the genesis branch from scratch at enterprise quality. VATDash integration bridge: VAT return preparation (UK MTD, EU OSS, EU MOSS), transaction tagging (VAT-applicable/exempt/reversed-charge), VAT rate lookups (EC VIES API + configurable override table), digital VAT report generation in JSON/CSV format, and HMRC Making Tax Digital (MTD) submission via pluggable `MtdAdapter`. Routes under `/vatdash`. Per-table SurrealQL. Events: `vatdash:vat-return:submitted`, `vatdash:transaction:tagged`.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
|
|
| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
|
|
| `@suaveplan/api-plugin-auth` (`workspace:^`) | `requireAuth`, `requireRole` |
|
|
| `@suaveplan/api-plugin-database` (`workspace:^`) | SurrealDB |
|
|
| `@suaveplan/api-plugin-export` (`workspace:^`) | Report export |
|
|
| `@suaveplan/datetime` (`workspace:^`) | VAT period date arithmetic |
|
|
| `@suaveplan/events` (`workspace:^`) | Event bus |
|
|
| `@suaveplan/error` (`workspace:^`) | `VatDashError` hierarchy |
|
|
| `@suaveplan/audit-logging` (`workspace:^`) | Submission audit |
|
|
| `hono` + `@hono/zod-openapi` + `zod` | Routes |
|
|
| `@opentelemetry/api` | OTel |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
function createVatdashBridgePlugin(config?: VatdashBridgeConfig): PluginDescriptor
|
|
interface MtdAdapter { submitReturn(return: VatReturn): Promise<MtdSubmissionResult> }
|
|
// Routes: /vatdash/transactions, /vatdash/vat-rates, /vatdash/returns,
|
|
// /vatdash/returns/:period/submit, /vatdash/returns/:period/report
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type VatDashErrorCode =
|
|
| "VATDASH_RETURN_NOT_FOUND"
|
|
| "VATDASH_PERIOD_ALREADY_SUBMITTED"
|
|
| "VATDASH_SUBMISSION_FAILED"
|
|
| "VATDASH_RATE_NOT_FOUND"
|
|
| "VATDASH_TRANSACTION_NOT_FOUND"
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
api/logistics/api-plugin-vatdash-bridge/
|
|
package.json tsconfig.json vitest.config.ts
|
|
surql/ (vat_transaction, vat_rate, vat_return tables)
|
|
src/
|
|
index.ts events.ts types/ errors/
|
|
adapters/mtd.port.ts
|
|
services/transaction/ services/vat-rate/ services/vat-return/ services/report/
|
|
routes/vatdash/
|
|
tests/integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
Prerequisites: `@suaveplan/api`, `@suaveplan/api-plugin-auth`, `@suaveplan/api-plugin-database`, `@suaveplan/api-plugin-export`, `@suaveplan/datetime`, `@suaveplan/audit-logging`.
|