OpenSpec Change: enterprise-api-plugin-customs

Change ID: enterprise-api-plugin-customs
Package: @suaveplan/api-plugin-customs
Category: api/logistics
Target path: api/logistics/api-plugin-customs
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/api-plugin-customs.md

Summary

Deliver @suaveplan/api-plugin-customs on the genesis branch from scratch at enterprise quality. The main-branch package is a skeleton (79 lines, no repos, no routes, no tests, placeholder event emission on startup). Genesis delivers the full implementation: customs declaration lifecycle (submitted/under-review/cleared/rejected), border-control holds (held/released), HS-code classification lookup, Intrastat reporting, duty payment tracking, and per-declaration document management. Routes under /customs. Per-table SurrealQL. Typed events (proper module augmentation — no as never/as Parameters<...> casts): customs:declaration:submitted, customs:declaration:cleared, customs:border:held, customs:border:released, customs:duty:paid.

Available workspace deps on genesis

Package	Role
`@suaveplan/api` (`workspace:^`)	`definePlugin`
`@suaveplan/api-shared` (`workspace:^`)	Helpers
`@suaveplan/api-plugin-auth` (`workspace:^`)	`requireAuth`
`@suaveplan/api-plugin-database` (`workspace:^`)	SurrealDB
`@suaveplan/api-plugin-logistics` (`workspace:^`)	Shipment reference
`@suaveplan/events` (`workspace:^`)	Event bus
`@suaveplan/error` (`workspace:^`)	`CustomsError` hierarchy
`@suaveplan/idempotency` (`workspace:^`)	Mutation guard
`@suaveplan/audit-logging` (`workspace:^`)	Audit trail
`@suaveplan/rate-limiter` (`workspace:^`)	Rate limits
`hono` + `@hono/zod-openapi` + `zod`	Routes
`@opentelemetry/api`	OTel

Public API surface

function createCustomsPlugin(config?: CustomsConfig): PluginDescriptor<CustomsConfig>
// Services: DeclarationService, BorderHoldService, HsCodeService, DutyService, IntrastatService
// Routes: /customs/declarations, /customs/declarations/:id,
//         /customs/declarations/:id/clear, /customs/border-holds,
//         /customs/hs-codes/lookup, /customs/intrastat

Error codes

type CustomsErrorCode =
  | "CUSTOMS_DECLARATION_NOT_FOUND"
  | "CUSTOMS_DECLARATION_ALREADY_CLEARED"
  | "CUSTOMS_BORDER_HOLD_NOT_FOUND"
  | "CUSTOMS_HS_CODE_NOT_FOUND"
  | "CUSTOMS_DUTY_PAYMENT_FAILED"
  | "CUSTOMS_INTRASTAT_PERIOD_CLOSED"

File layout

api/logistics/api-plugin-customs/
  package.json  tsconfig.json  vitest.config.ts
  surql/ (customs_declaration, border_hold, hs_code, duty_payment, intrastat_report tables)
  src/
    index.ts  events.ts  types/  errors/
    services/declaration/  services/border-hold/  services/hs-code/
    services/duty/  services/intrastat/
    routes/customs/
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/api-plugin-logistics, @suaveplan/events, @suaveplan/idempotency, @suaveplan/audit-logging.

3.1 KiB Raw Permalink Blame History