suaveplan/openspec/archive/2026-05-19-add-api-plugin-export/proposal.md

Ship @suaveplan/api-plugin-export

Package: @suaveplan/api-plugin-export Status: PROPOSED Type: new-package

Why

The genesis monorepo needs a data-export plugin for @suaveplan/api that turns any registered resource into a CSV (RFC 4180), JSON, or XLSX (SpreadsheetML XML) blob. The upstream package at ../suaveplan/packages/server/api-plugin-export/ (v1.0.5) ships three self-contained exporter classes, a DataProvider registry, a job-lifecycle store, and an OpenAPIHono route group at /exports. This change rebuilds that surface at genesis-quality (SuaveplanError codes, OTel instruments asserted with a real MeterProvider, 100 % istanbul coverage, sibling .md for every implementation file, no mocks, no vi.mock, no export * in feature barrels).

What changes

• ADDED: createExportPlugin(options?) — returns a PluginDescriptor honouring caller-supplied options (the upstream _config-discard bug is fixed at migration time).
• ADDED: CsvExporter, JsonExporter, XlsxExporter — three RFC-4180 / JSON / SpreadsheetML implementations of the Exporter interface.
• ADDED: getExporter(format), inferColumns(data), runExport(...), DEFAULT_EXPORT_CONFIG — service-layer helpers.
• ADDED: createExportRoutes(deps) — OpenAPIHono with GET /, POST /, GET /:id, DELETE /:id.
• ADDED: registerDataProvider(providers, provider) — providers-map helper.
• ADDED: EXPORT_CODES + ExportError extending SuaveplanError — replaces the raw new Error(...) throws from upstream export.service.ts.
• ADDED: ExportInstruments + getExportInstruments() + resetExportInstruments() — OTel Counter + Histogram bundle.
• ADDED: Zod schemas ExportFormatSchema, ExportStatusSchema, ColumnDefinitionSchema, CreateExportJobSchema, ExportJobSchema, ExportJobListQuerySchema, ExportPluginOptionsSchema.
• ADDED: ServiceRegistry slots exportProviders and exportJobs via declare module "@suaveplan/api-plugin/service-registry".

Out of scope

This change ships the upstream §2 “Current-state assessment” surface only. The upstream enterprise/api-plugin-export.md §3–§4 enhancements (streaming exporters, S3-backed blob store, auth/permissions/rate-limit/idempotency middleware, OOXML/ZIP writer, scheduled exports, signed download URLs, Parquet/Markdown formats, benchmark harness) are explicitly deferred — they are listed as “feature-rich enhancements” in the source spec, not as part of the current functional surface, and each requires a downstream plugin that has not yet landed on genesis (e.g. @suaveplan/data-masking, @suaveplan/storage-s3, @suaveplan/api-plugin-rate-limit consumer wiring, @suaveplan/queue).

Excluded from this migration

Upstream symbol / behaviour	Justification
ctx.app.route(basePath, routes) mount in onReady	Genesis PluginContext has no app field; routes are exposed via ctx.getService("app") in onReady (same pattern as @suaveplan/api-plugin-audit). Public route surface is preserved.
ctx.eventBus.emit("export:initialized" / "export:ready" / "export:started" / "export:completed")	Genesis EventBusLike is structural and does not declare these event keys in ServiceRegistry. Replaced with structured logger calls + OTel counter; the onExportStarted / onExportCompleted callback hooks remain on createExportRoutes deps so consumers can wire any bus they want.
declare module "@suaveplan/api" { interface EventMap { ... } }	Same reason as above — no EventMap interface on genesis @suaveplan/api.
GET /:id/download streaming endpoint	Upstream enterprise/api-plugin-export.md §2 "Smells" notes the response uses downloadUrl: "/{jobId}/download" but no /:id/download handler exists in routes/exports.ts. The endpoint is part of §3 "Required enterprise-quality improvements" and §4 "Streaming exporters" — deferred to follow-up. The downloadUrl field is retained for forward compatibility.
§3 "Job persistence" via SurrealDB	Upstream §2 ships the in-memory Map<string, ExportJob>. SurrealDB persistence is §3 work and requires surql/ migrations + integration tests against @suaveplan/api-plugin-database. Deferred.
§4 streaming / S3 / OOXML / auth / rate-limit / idempotency / audit / signed URLs / Parquet / Markdown / scheduled exports / benchmarks	All listed as “feature-rich enhancements” in upstream §4. Deferred per Out-of-scope above.

Source mapping

This change derives from ../suaveplan/enterprise/api-plugin-export.md and the upstream source under ../suaveplan/packages/server/api-plugin-export/src/.

Requirement	Source lines	Notes
Plugin name "export" v1.0.0, optionalDependencies: ["database", "events"], tags: ["export","data","csv","json","xlsx"]	enterprise/api-plugin-export.md L18 + src/index.ts:44-50	verbatim
Config schema basePath / maxRows (1–1 000 000) / maxFileSizeBytes (≥ 1 KiB, default 50 MiB) / defaultFormat (csv|json|xlsx)	enterprise/api-plugin-export.md L18 + src/index.ts:21-30	verbatim
Honour factory-time config — merge caller-supplied options with getOwnConfig()	enterprise/api-plugin-export.md L34 + L43	upstream bug fixed at migration time
Three exporter classes: CsvExporter, JsonExporter, XlsxExporter implementing Exporter	enterprise/api-plugin-export.md L17 + src/exporters/{csv,json,xlsx}/*.ts	verbatim
RFC 4180 CSV: configurable delimiter, optional headers, quote-escaping, ISO-8601 dates, text/csv MIME	enterprise/api-plugin-export.md L26 + src/exporters/csv/csv.exporter.ts	verbatim
JSON: column projection + optional pretty-print, application/json MIME	enterprise/api-plugin-export.md L27 + src/exporters/json/json.exporter.ts	verbatim
XLSX (SpreadsheetML XML): configurable sheet name, header row, OOXML MIME, A→Z→AA column letters	enterprise/api-plugin-export.md L28 + src/exporters/xlsx/xlsx.exporter.ts	verbatim
Service helpers: getExporter, inferColumns, runExport, DEFAULT_EXPORT_CONFIG with row/size guards	enterprise/api-plugin-export.md L24 + src/services/export/export.service.ts	verbatim, with ExportError replacing raw Error
Routes: GET /, POST /, GET /:id, DELETE /:id on OpenAPIHono	enterprise/api-plugin-export.md L25 + src/routes/exports/exports.ts	verbatim (download endpoint excluded — see above)
In-memory Map<string, ExportJob> job store with pending|processing|completed|failed FSM	enterprise/api-plugin-export.md L25 + L31 + src/routes/exports/exports.ts:140-213	verbatim
Zod boundaries on every public option bundle (CreateExportJobSchema, ExportJobListQuerySchema, ExportJobSchema)	enterprise/api-plugin-export.md L23 + src/types.ts:32-87	verbatim
registerDataProvider(providers, provider) helper	src/index.ts:109-114	verbatim

Requirements with no source line

Requirement	Justification
EXPORT_CODES + ExportError extends SuaveplanError	Genesis-wide policy (CLAUDE.md §“Error hierarchy”). Upstream throws raw Error.
ExportInstruments + getExportInstruments + resetExportInstruments with export.jobs_total{outcome}, export.rows_total, export.bytes_total, export.duration_ms	Genesis-wide OTel policy. Upstream has no OTel.
ServiceRegistry slots exportProviders / exportJobs via declare module	Required because genesis PluginContext exposes services only via the augmented registry — there is no upstream equivalent because the upstream PluginContext is structurally different (has ctx.app, ctx.eventBus.emit(K, payload), etc.).
100 % istanbul coverage; sibling .md ≥ 200 words per impl file	Genesis-wide policy.
spec-conformance.test.ts pinning every EXPORT_* code to ≥ 1 production throw site	Genesis policy (§13).

Verification approach

• src/error-codes/error-codes.test.ts — every EXPORT_* code constructs an ExportError with the right narrowed code.
• src/exporters/csv/csv.test.ts — RFC 4180 quoting / delimiter / header / ISO-8601 date round-trip.
• src/exporters/json/json.test.ts — projection, pretty-print, transform application.
• src/exporters/xlsx/xlsx.test.ts — sheet name, header row, column letter math A→Z→AA, escaping.
• src/services/export/export-service.test.ts — getExporter, inferColumns, runExport row + size guards (throw ExportError).
• src/routes/exports/exports.test.ts — GET / filter+pagination, POST / happy + 404 + 400 (row cap) + 400 (size cap) + 400 (provider error), GET /:id + 404, DELETE /:id + 404.
• src/plugin/plugin.test.ts — Zod validation rejects bad options; onInit registers exportProviders + exportJobs; onReady honours caller-supplied options and mounts routes via ctx.getService("app"); onClose clears both maps.
• src/otel/instruments.test.ts — emits all four instruments through a real in-memory MeterProvider.
• src/api-plugin-export.spec-conformance.test.ts — every EXPORT_* code is thrown from a non-test file; side-effect imports of error-codes and registry-augmentation are present in index.ts.

Migration impact

None — additive only. No genesis package currently consumes @suaveplan/api-plugin-export.