suaveplan/packages/api-stack/api/api-plugin-export/README.md

# @suaveplan/api-plugin-export - Data-export plugin for @suaveplan/api: CSV (RFC 4180), JSON, and XLSX (SpreadsheetML XML) exporters, in-memory job store, OpenAPIHono route group at /exports, ExportError hierarchy, OTel instruments.

Data-export plugin for `@suaveplan/api`. Turns any registered resource into a CSV (RFC 4180), JSON, or XLSX (SpreadsheetML XML) blob through three self-contained exporter classes, a `DataProvider` registry, an in-memory job-lifecycle store, and an `OpenAPIHono` route group at the configured `basePath` (default `/exports`).

<!-- begin:auto-docs -->
## Documentation tree

- [error-codes](./src/error-codes/error-codes.md) — This module owns the stable error-code registry for `@suaveplan/api-plugin-export`. Every production code path that rai…
  - [error-codes](./src/error-codes/error-codes.md) — This module owns the stable error-code registry for `@suaveplan/api-plugin-export`. Every production code path that rai…
- [csv](./src/exporters/csv/csv.md) — RFC 4180 CSV writer. This module ships three pure helpers — `escapeCsvField`, `formatCellValue`, `convertToCsv` — plus…
  - [csv](./src/exporters/csv/csv.md) — RFC 4180 CSV writer. This module ships three pure helpers — `escapeCsvField`, `formatCellValue`, `convertToCsv` — plus…
- [json](./src/exporters/json/json.md) — JSON exporter. Projects every row to a record keyed by the column `header` (not `key`), optionally applying `column.tra…
  - [json](./src/exporters/json/json.md) — JSON exporter. Projects every row to a record keyed by the column `header` (not `key`), optionally applying `column.tra…
- [xlsx](./src/exporters/xlsx/xlsx.md) — SpreadsheetML (XML) writer for the `xlsx` format. This is the dependency-free path inherited from the upstream package…
  - [xlsx](./src/exporters/xlsx/xlsx.md) — SpreadsheetML (XML) writer for the `xlsx` format. This is the dependency-free path inherited from the upstream package…
- [otel](./src/otel/instruments.md) — OpenTelemetry instrument factory for `@suaveplan/api-plugin-export`. Builds a cached bundle of six instruments — five c…
  - [instruments](./src/otel/instruments.md) — OpenTelemetry instrument factory for `@suaveplan/api-plugin-export`. Builds a cached bundle of six instruments — five c…
- [plugin](./src/plugin/plugin.md) — The plugin factory for `@suaveplan/api-plugin-export`. Construction-time it validates options through `ExportPluginOpti…
  - [plugin](./src/plugin/plugin.md) — The plugin factory for `@suaveplan/api-plugin-export`. Construction-time it validates options through `ExportPluginOpti…
- [download](./src/routes/download/download.md) — Implements the `GET /:id/download` route on `@suaveplan/api-plugin-export`. The handler serves the rendered file body f…
  - [download](./src/routes/download/download.md) — Implements the `GET /:id/download` route on `@suaveplan/api-plugin-export`. The handler serves the rendered file body f…
- [exports](./src/routes/exports/exports.md) — OpenAPIHono route group exposed at the configured `basePath` (default `/exports`). Wires four endpoints — `GET /`, `POS…
  - [exports](./src/routes/exports/exports.md) — OpenAPIHono route group exposed at the configured `basePath` (default `/exports`). Wires four endpoints — `GET /`, `POS…
  - [post-handler](./src/routes/exports/post-handler.md) — Implementation of the `POST /exports` handler, extracted from `exports.ts` so the route-registration file stays under t…
- [problem-json](./src/routes/problem-json/problem-json.md) — `@suaveplan/api-plugin-export` returns RFC 7807 `application/problem+json` bodies for every failure surface on its rout…
  - [problem-json](./src/routes/problem-json/problem-json.md) — `@suaveplan/api-plugin-export` returns RFC 7807 `application/problem+json` bodies for every failure surface on its rout…
- [services](./src/services/registry-augmentation.md) — This file is a type-only `declare module "@suaveplan/api-plugin/service-registry"` block. It adds two slots to the shar…
  - [export](./src/services/export/export-service.md) — Service-level orchestration for the export plugin. This module wires the three exporter classes (`CsvExporter`, `JsonEx…
    - [export-service](./src/services/export/export-service.md) — Service-level orchestration for the export plugin. This module wires the three exporter classes (`CsvExporter`, `JsonEx…
  - [registry-augmentation](./src/services/registry-augmentation.md) — This file is a type-only `declare module "@suaveplan/api-plugin/service-registry"` block. It adds two slots to the shar…
- [memory](./src/store/memory/memory-store.md) — This module ships `MemoryExportJobStore`, the in-memory implementation of the `ExportJobStore` contract. It wraps a `Ma…
  - [memory-store](./src/store/memory/memory-store.md) — This module ships `MemoryExportJobStore`, the in-memory implementation of the `ExportJobStore` contract. It wraps a `Ma…
- [surreal](./src/store/surreal/surreal-store.md) — This module ships `SurrealExportStore`, the SurrealDB-backed implementation of `ExportJobStore`. It satisfies the same…
  - [surreal-store](./src/store/surreal/surreal-store.md) — This module ships `SurrealExportStore`, the SurrealDB-backed implementation of `ExportJobStore`. It satisfies the same…
- [types](./src/store/types/types.md) — This module declares the `ExportJobStore` interface — the formal persistence contract for export jobs. Before this modu…
  - [types](./src/store/types/types.md) — This module declares the `ExportJobStore` interface — the formal persistence contract for export jobs. Before this modu…
- [types](./src/types/types.md) — This module holds the Zod-fronted public type surface for `@suaveplan/api-plugin-export`: the `ExportFormat` / `ExportS…
  - [types](./src/types/types.md) — This module holds the Zod-fronted public type surface for `@suaveplan/api-plugin-export`: the `ExportFormat` / `ExportS…
<!-- end:auto-docs -->

## Quick start

```ts
import { createPluginRegistry } from "@suaveplan/api-plugin";
import {
    createExportPlugin,
    type DataProvider,
} from "@suaveplan/api-plugin-export";

const registry = createPluginRegistry();
registry.register(createExportPlugin({ basePath: "/v1/exports" }));
await registry.init();
await registry.ready();

const providers = registry.getService("exportProviders");
if (providers) {
    const userProvider: DataProvider = {
        resource: "users",
        fetch: async () => db.select("user").get(),
    };
    providers.set(userProvider.resource, userProvider);
}
```

```http
POST /v1/exports/  → { format: "csv", resource: "users" }
GET  /v1/exports/  → { items: ExportJob[], total }
GET  /v1/exports/{id}  → ExportJob
DELETE /v1/exports/{id}  → { success: true }
```

## Modules

- [`plugin/plugin`](src/plugin/plugin.md) — plugin factory + lifecycle hooks.
- [`routes/exports/exports`](src/routes/exports/exports.md) — OpenAPIHono route group.
- [`routes/exports/post-handler`](src/routes/exports/post-handler.md) — `POST /` handler.
- [`services/export/export-service`](src/services/export/export-service.md) — `getExporter`, `inferColumns`, `runExport`.
- [`exporters/csv/csv`](src/exporters/csv/csv.md) — RFC 4180 CSV writer.
- [`exporters/json/json`](src/exporters/json/json.md) — JSON writer.
- [`exporters/xlsx/xlsx`](src/exporters/xlsx/xlsx.md) — SpreadsheetML XML writer.
- [`error-codes/error-codes`](src/error-codes/error-codes.md) — `EXPORT_CODES` + `ExportError`.
- [`otel/instruments`](src/otel/instruments.md) — `ExportInstruments` bundle.
- [`services/registry-augmentation`](src/services/registry-augmentation.md) — `ServiceRegistry` slot augmentation.
- [`types/types`](src/types/types.md) — Zod schemas + public types.

## Scope notes

This package ships the upstream §2 functional surface (CSV / JSON / SpreadsheetML XML exporters + in-memory job store + four-route Hono group). The upstream §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) are deferred to follow-up changes — they require downstream plugins that have not yet landed .