OpenSpec Change: enterprise-api-plugin-gtap

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

Summary

Deliver @suaveplan/api-plugin-gtap on the genesis branch from scratch at enterprise quality. Global Trade Automation Platform (GTAP) integration bridge: import/export license management, tariff classification (HS code + origin), sanctioned-party screening (OFAC/EU/UN lists via pluggable SanctionScreenAdapter), certificate-of-origin generation, preferential-trade-agreement (PTA) eligibility checking, and AEO (Authorised Economic Operator) status tracking. Routes under /gtap. Per-table SurrealQL. Events: gtap:sanction:hit, gtap:certificate:issued, gtap:license:expired.

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-customs` (`workspace:^`)	HS code reference
`@suaveplan/audit-logging` (`workspace:^`)	Sanction hit + license audit
`@suaveplan/events` (`workspace:^`)	Event bus
`@suaveplan/error` (`workspace:^`)	`GtapError` hierarchy
`hono` + `@hono/zod-openapi` + `zod`	Routes
`@opentelemetry/api`	OTel

Public API surface

function createGtapPlugin(config?: GtapConfig): PluginDescriptor
interface SanctionScreenAdapter { screen(entity: ScreenRequest): Promise<ScreenResult> }
// Routes: /gtap/licenses, /gtap/screen, /gtap/certificates,
//         /gtap/pta-eligibility, /gtap/aeo-status

Error codes

type GtapErrorCode =
  | "GTAP_LICENSE_NOT_FOUND"
  | "GTAP_LICENSE_EXPIRED"
  | "GTAP_SANCTION_HIT"
  | "GTAP_CERTIFICATE_NOT_FOUND"
  | "GTAP_PTA_NOT_ELIGIBLE"

File layout

api/logistics/api-plugin-gtap/
  package.json  tsconfig.json  vitest.config.ts
  surql/ (trade_license, sanction_screening_log, certificate_of_origin, aeo_status tables)
  src/
    index.ts  events.ts  types/  errors/
    adapters/sanction-screen.port.ts
    services/license/  services/screening/  services/certificate/
    services/pta/  services/aeo/
    routes/gtap/
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/api-plugin-customs, @suaveplan/audit-logging.

2.7 KiB Raw Blame History