@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.10

package/dist/exports/export.types.d.ts

@@ -0,0 +1,217 @@
+import type { Writable } from 'node:stream';
+import type { ExportCell, ExportColumn, ExportColumnType, ExportRequestField, ExportScope } from '@marinoscar/platform-contract/exports';
+import type { z } from 'zod';
+import type { ExportDatamodel } from './datamodel';
+export type { ExportCell, ExportColumn, ExportColumnType, ExportRequestField, ExportScope };
+/**
+ * One row of a dataset, keyed by column key. A key a row lacks is written as
+ * `null`.
+ *
+ * @stability experimental
+ */
+export type ExportRow = Readonly<Record<string, ExportCell>>;
+/**
+ * One dataset: a named, titled table whose rows arrive lazily.
+ *
+ * @stability experimental
+ */
+export interface ExportTable {
+    /** The dataset name (`personal_access_token`): a JSON key and a zip entry name; matches `EXPORT_DATASET_PATTERN`. */
+    readonly dataset: string;
+    /** The human title: an XLSX sheet name, a heading. */
+    readonly title: string;
+    /** The columns, in order. */
+    readonly columns: readonly ExportColumn[];
+    /**
+     * The rows, produced on demand. A source pages its query (cursor by id) and
+     * yields as it goes; it never loads a whole table. Iterated exactly once.
+     */
+    readonly rows: AsyncIterable<ExportRow>;
+}
+/**
+ * The client a source reads through: the app's bypass client (`asSystem`),
+ * seen untyped. Every query names its owner or organization explicitly; row-
+ * level security does not filter it (that is the point: a user's own rows sit
+ * in several organizations, and an organization's export must see every row
+ * of that organization whoever's scope is active).
+ *
+ * @stability experimental
+ */
+export type ExportDb = {
+    readonly [delegate: string]: any;
+};
+/**
+ * What a source's `collect` receives.
+ *
+ * @stability experimental
+ */
+export interface ExportContext {
+    /** The export (job) id. */
+    readonly exportId: string;
+    /** The source's scope. */
+    readonly scope: ExportScope;
+    /** Whose data: the user id (`user` scope) or the organization id (`org` scope). */
+    readonly subjectId: string;
+    /** The user who asked for it. */
+    readonly requestedById: string;
+    /** The client to read through ({@link ExportDb}); read-only use only. */
+    readonly db: ExportDb;
+    /** The app's data model (`Prisma.dmmf.datamodel`), for sources that derive columns from it. */
+    readonly datamodel: ExportDatamodel;
+    /** Rows per page when a source pages a query. */
+    readonly pageSize: number;
+    /** The export's clock: one instant for the whole export. */
+    readonly now: Date;
+}
+/**
+ * A registered source of export data (rung 2).
+ *
+ * @typeParam Req - the parsed request.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * registerExportSource({
+ *   id: 'health', scope: 'user', label: 'Health data', permission: 'health_data:read',
+ *   requestSchema: z.object({ from: z.iso.date(), to: z.iso.date() }).strict(),
+ *   formats: ['json', 'csv', 'xlsx'],
+ *   async *collect(ctx, req) { yield healthTable(ctx, req); },
+ * });
+ * ```
+ */
+export interface ExportSource<Req = unknown> {
+    /** Permanent once jobs carry it, e.g. `'user-data'`; matches `EXPORT_ID_PATTERN`. */
+    readonly id: string;
+    /** Whose data it exports. */
+    readonly scope: ExportScope;
+    /** What the dialog calls it. */
+    readonly label: string;
+    /** One sentence about what it contains. */
+    readonly description?: string;
+    /** The exact permission string the route enforces for this source. */
+    readonly permission: string;
+    /**
+     * `org` scope only: the permission that lets a caller export an
+     * organization OTHER than the active one (a system administrator's
+     * `organizations:read`). Without it, only the active organization.
+     */
+    readonly crossOrgPermission?: string;
+    /** Validated at the route AND when the job starts; `.strict()` recommended. */
+    readonly requestSchema: z.ZodType<Req>;
+    /** The request fields the dialog draws; derived from `requestSchema` when absent. */
+    readonly fields?: readonly ExportRequestField[];
+    /**
+     * The writer ids it offers, in display order; a subset of the registered
+     * writers. May be empty: the platform sources list none and offer exactly
+     * the writers that attach to them (`ExportWriter.attachTo`), json, csv and
+     * xlsx by default. Writers that attach come after the ones listed here.
+     */
+    readonly formats: readonly string[];
+    /**
+     * The column types this source's datasets use. Declare it so a writer that
+     * attaches to `'*'` only reaches sources whose columns it can write. Absent
+     * means "unknown": every type is assumed, so a writer restricted with
+     * `ExportWriter.columnTypes` does not attach to this source on its own.
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    readonly columnTypes?: readonly ExportColumnType[];
+    /**
+     * Whether writers that attach themselves (`ExportWriter.attachTo`) are
+     * offered next to `formats`. Default `true`; `false` pins the source to the
+     * writers it lists (a source that must only ever leave in formats its owner
+     * reviewed).
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    readonly acceptsAttachedWriters?: boolean;
+    /**
+     * The datasets. READ-ONLY: never writes a row. Pages its queries and yields
+     * tables lazily; must not load whole tables into memory.
+     */
+    collect(ctx: ExportContext, req: Req): AsyncIterable<ExportTable>;
+    /**
+     * The download name, without the extension's dot handled for you:
+     * return the full name. Must match `EXPORT_FILE_NAME_PATTERN`. Default
+     * `<app-slug>-<source>-<YYYY-MM-DD>.<ext>`.
+     */
+    fileName?(ctx: ExportContext, req: Req, ext: string): string;
+}
+/**
+ * What a writer receives besides the tables.
+ *
+ * @stability experimental
+ */
+export interface ExportWriteContext {
+    /** The source id. */
+    readonly source: string;
+    /** When the export was produced. */
+    readonly exportedAt: Date;
+    /** The app's file-name slug (`my-app`), for document metadata. */
+    readonly appSlug: string;
+}
+/**
+ * What a writer reports when it finished.
+ *
+ * @stability experimental
+ */
+export interface ExportWriteResult {
+    /** Rows written per dataset. */
+    readonly rowCounts: Readonly<Record<string, number>>;
+}
+/**
+ * A registered output format (rung 2).
+ *
+ * THE CONTRACT (kvox's, kept): `write` writes the complete file to `out` and
+ * ENDS it; the returned promise settles only once `out` has finished; a
+ * failure rejects AND destroys `out`, so a half-written file never reaches
+ * storage looking complete. It honours backpressure (`writeChunk`), so it
+ * never buffers the file.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * registerExportWriter({
+ *   id: 'ndjson', label: 'NDJSON', mimeType: 'application/x-ndjson', extension: 'ndjson',
+ *   async write(tables, out) { ... },
+ * });
+ * ```
+ */
+export interface ExportWriter {
+    /** The format id (`csv`); permanent once jobs carry it. */
+    readonly id: string;
+    /** What the dialog calls it. */
+    readonly label: string;
+    /** The file's media type (`application/zip` for `csv`). */
+    readonly mimeType: string;
+    /** The file's extension, without the dot (`zip` for `csv`). */
+    readonly extension: string;
+    /** Limits the writer to these sources (a domain PDF); absent means any source that lists it. */
+    readonly sources?: readonly string[];
+    /**
+     * Attaches the writer to sources that do not list it: `'*'` offers it on
+     * every source whose columns it can write (see {@link ExportWriter.columnTypes}
+     * and `ExportSource.columnTypes`), a list of source ids on exactly those.
+     * `sources`, when given, still narrows. The writer receives the same
+     * redacted rows as the built-in writers, because the source produces them
+     * before any writer runs. Absent: only sources that list the writer offer it.
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    readonly attachTo?: '*' | readonly string[];
+    /**
+     * The column types the writer can serialise. Absent means all of them. A
+     * dataset with a column of another type fails the export with a message
+     * naming the column (the half-written file is destroyed, never uploaded).
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    readonly columnTypes?: readonly ExportColumnType[];
+    /** Serialises `tables` into `out`. See the contract above. */
+    write(tables: AsyncIterable<ExportTable>, out: Writable, ctx: ExportWriteContext): Promise<ExportWriteResult>;
+}
+//# sourceMappingURL=export.types.d.ts.map

package/dist/exports/export.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.types.d.ts","sourceRoot":"","sources":["../../src/exports/export.types.ts"],"names":[],"mappings":"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"}

package/dist/exports/export.types.js

@@ -0,0 +1,19 @@
+"use strict";
+// =============================================================================
+// The export framework's contracts: tables, sources and writers (issue #744)
+// =============================================================================
+//
+// A SOURCE turns a request into datasets (`ExportTable`s); a WRITER serialises
+// datasets into one file. The `export.run` job pairs one of each: it asks the
+// source for its tables and streams the writer's output straight into object
+// storage. Neither side ever holds a whole table: `rows` is an
+// `AsyncIterable`, a writer writes to a `Writable` with backpressure, and the
+// upload consumes it as it is produced (the backup engine's "never buffered"
+// discipline, and kvox's "`render` streams, it does not return a buffer").
+//
+// The shapes are EvoPath's (`health-export-data.ts`: `ExportCell`,
+// `ExportColumn`, `ExportTable`) with `rows` made lazy, and kvox's exporter
+// contract for writers (a `Writable` out, ended by the writer).
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=export.types.js.map

package/dist/exports/export.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.types.js","sourceRoot":"","sources":["../../src/exports/export.types.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,6EAA6E;AAC7E,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,+DAA+D;AAC/D,8EAA8E;AAC9E,6EAA6E;AAC7E,2EAA2E;AAC3E,EAAE;AACF,mEAAmE;AACnE,4EAA4E;AAC5E,gEAAgE;AAChE,gFAAgF"}

package/dist/exports/exports.constants.d.ts

@@ -0,0 +1,109 @@
+import type { StorageKeyPrefixDef } from '../storage/index';
+/**
+ * The export job. PERMANENT once rows of it exist.
+ *
+ * @stability experimental
+ */
+export declare const EXPORT_RUN_JOB_TYPE = "export.run";
+/**
+ * The housekeeping job that deletes expired export files. PERMANENT.
+ *
+ * @stability experimental
+ */
+export declare const EXPORT_PURGE_JOB_TYPE = "export.purge";
+/**
+ * `Job.subjectType` of a user export (`subjectId` is the user id). The same
+ * value the user-data reset matches when it deletes a user's pending jobs.
+ *
+ * @stability experimental
+ */
+export declare const EXPORT_USER_SUBJECT_TYPE = "user";
+/**
+ * `Job.subjectType` of an organization export (`subjectId` is the
+ * organization id), the jobs README's convention for org-scoped work.
+ *
+ * @stability experimental
+ */
+export declare const EXPORT_ORG_SUBJECT_TYPE = "organization";
+/**
+ * The audit action written when an export file is produced. Its `meta` holds
+ * the source, the format, the row counts and the size: never a value, a file
+ * name or a URL.
+ *
+ * @stability experimental
+ */
+export declare const EXPORT_AUDIT_ACTION = "export:create";
+/**
+ * The audit `targetType`; `targetId` is the export (job) id.
+ *
+ * @stability experimental
+ */
+export declare const EXPORT_AUDIT_TARGET = "export";
+/**
+ * `storage_objects.metadata.source` of an export file: the user-data reset's
+ * `files` category deletes it with the rest of the user's uploads.
+ *
+ * @stability experimental
+ */
+export declare const EXPORT_OBJECT_SOURCE = "export";
+/**
+ * Every export file lives under this root (both prefixes below). The purge
+ * selects rows by it. Not a `*_KEY_PREFIX`: the key-prefix tripwire would
+ * read it as a third, unregistered prefix.
+ *
+ * @stability experimental
+ */
+export declare const EXPORTS_STORAGE_ROOT = "exports/";
+/**
+ * A user's exports: `exports/users/<userId>/<exportId>.<ext>`.
+ *
+ * @stability experimental
+ */
+export declare const EXPORTS_USERS_KEY_PREFIX = "exports/users/";
+/**
+ * An organization's exports: `exports/orgs/<orgId>/<exportId>.<ext>`, one
+ * listable prefix per organization (`orgKeyPrefixes`), so offboarding never
+ * scans the bucket.
+ *
+ * @stability experimental
+ */
+export declare const EXPORTS_ORGS_KEY_PREFIX = "exports/orgs/";
+/**
+ * The slice's object-key prefixes, for the app's key-prefix manifest (so the
+ * standalone storage purge reaches them) and for `ExportsModule.forRoot()`,
+ * which registers them too (idempotent).
+ *
+ * @stability experimental
+ */
+export declare const EXPORTS_KEY_PREFIXES: readonly StorageKeyPrefixDef[];
+/**
+ * How long an export file is kept: 7 days.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_EXPORT_RETENTION_DAYS = 7;
+/**
+ * Lifetime of a signed download URL: 300 seconds.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_EXPORT_DOWNLOAD_URL_TTL_SECONDS = 300;
+/**
+ * Exports one subject may have pending or running at once; the next is a 429.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_EXPORT_MAX_IN_FLIGHT = 3;
+/**
+ * Rows read per page by the platform sources.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_EXPORT_PAGE_SIZE = 500;
+/**
+ * Storage rows the purge reads per batch.
+ *
+ * @stability stable
+ */
+export declare const EXPORT_PURGE_BATCH = 200;
+//# sourceMappingURL=exports.constants.d.ts.map

package/dist/exports/exports.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports.constants.d.ts","sourceRoot":"","sources":["../../src/exports/exports.constants.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,iBAAiB,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,SAAS,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,aAAa,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,kBAAkB,CAAC;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,mBAAmB,EAe7D,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,uCAAuC,MAAM,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAC"}

package/dist/exports/exports.constants.js

@@ -0,0 +1,133 @@
+"use strict";
+// =============================================================================
+// The exports slice's constants (issue #744)
+// =============================================================================
+//
+// Job types, audit names, the storage key prefixes and the defaults (EvoPath's
+// `health-export.constants.ts` values). Plain data, no Nest import.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPORT_PURGE_BATCH = exports.DEFAULT_EXPORT_PAGE_SIZE = exports.DEFAULT_EXPORT_MAX_IN_FLIGHT = exports.DEFAULT_EXPORT_DOWNLOAD_URL_TTL_SECONDS = exports.DEFAULT_EXPORT_RETENTION_DAYS = exports.EXPORTS_KEY_PREFIXES = exports.EXPORTS_ORGS_KEY_PREFIX = exports.EXPORTS_USERS_KEY_PREFIX = exports.EXPORTS_STORAGE_ROOT = exports.EXPORT_OBJECT_SOURCE = exports.EXPORT_AUDIT_TARGET = exports.EXPORT_AUDIT_ACTION = exports.EXPORT_ORG_SUBJECT_TYPE = exports.EXPORT_USER_SUBJECT_TYPE = exports.EXPORT_PURGE_JOB_TYPE = exports.EXPORT_RUN_JOB_TYPE = void 0;
+/**
+ * The export job. PERMANENT once rows of it exist.
+ *
+ * @stability experimental
+ */
+exports.EXPORT_RUN_JOB_TYPE = 'export.run';
+/**
+ * The housekeeping job that deletes expired export files. PERMANENT.
+ *
+ * @stability experimental
+ */
+exports.EXPORT_PURGE_JOB_TYPE = 'export.purge';
+/**
+ * `Job.subjectType` of a user export (`subjectId` is the user id). The same
+ * value the user-data reset matches when it deletes a user's pending jobs.
+ *
+ * @stability experimental
+ */
+exports.EXPORT_USER_SUBJECT_TYPE = 'user';
+/**
+ * `Job.subjectType` of an organization export (`subjectId` is the
+ * organization id), the jobs README's convention for org-scoped work.
+ *
+ * @stability experimental
+ */
+exports.EXPORT_ORG_SUBJECT_TYPE = 'organization';
+/**
+ * The audit action written when an export file is produced. Its `meta` holds
+ * the source, the format, the row counts and the size: never a value, a file
+ * name or a URL.
+ *
+ * @stability experimental
+ */
+exports.EXPORT_AUDIT_ACTION = 'export:create';
+/**
+ * The audit `targetType`; `targetId` is the export (job) id.
+ *
+ * @stability experimental
+ */
+exports.EXPORT_AUDIT_TARGET = 'export';
+/**
+ * `storage_objects.metadata.source` of an export file: the user-data reset's
+ * `files` category deletes it with the rest of the user's uploads.
+ *
+ * @stability experimental
+ */
+exports.EXPORT_OBJECT_SOURCE = 'export';
+/**
+ * Every export file lives under this root (both prefixes below). The purge
+ * selects rows by it. Not a `*_KEY_PREFIX`: the key-prefix tripwire would
+ * read it as a third, unregistered prefix.
+ *
+ * @stability experimental
+ */
+exports.EXPORTS_STORAGE_ROOT = 'exports/';
+/**
+ * A user's exports: `exports/users/<userId>/<exportId>.<ext>`.
+ *
+ * @stability experimental
+ */
+exports.EXPORTS_USERS_KEY_PREFIX = 'exports/users/';
+/**
+ * An organization's exports: `exports/orgs/<orgId>/<exportId>.<ext>`, one
+ * listable prefix per organization (`orgKeyPrefixes`), so offboarding never
+ * scans the bucket.
+ *
+ * @stability experimental
+ */
+exports.EXPORTS_ORGS_KEY_PREFIX = 'exports/orgs/';
+/**
+ * The slice's object-key prefixes, for the app's key-prefix manifest (so the
+ * standalone storage purge reaches them) and for `ExportsModule.forRoot()`,
+ * which registers them too (idempotent).
+ *
+ * @stability experimental
+ */
+exports.EXPORTS_KEY_PREFIXES = Object.freeze([
+    Object.freeze({
+        id: 'exports-users',
+        prefix: exports.EXPORTS_USERS_KEY_PREFIX,
+        owner: 'exports',
+        scope: 'user',
+        description: "Data exports of one user, under exports/users/<userId>/, deleted after the retention period.",
+    }),
+    Object.freeze({
+        id: 'exports-orgs',
+        prefix: exports.EXPORTS_ORGS_KEY_PREFIX,
+        owner: 'exports',
+        scope: 'org',
+        description: "Data exports of one organization, under exports/orgs/<orgId>/, deleted after the retention period.",
+    }),
+]);
+/**
+ * How long an export file is kept: 7 days.
+ *
+ * @stability stable
+ */
+exports.DEFAULT_EXPORT_RETENTION_DAYS = 7;
+/**
+ * Lifetime of a signed download URL: 300 seconds.
+ *
+ * @stability stable
+ */
+exports.DEFAULT_EXPORT_DOWNLOAD_URL_TTL_SECONDS = 300;
+/**
+ * Exports one subject may have pending or running at once; the next is a 429.
+ *
+ * @stability stable
+ */
+exports.DEFAULT_EXPORT_MAX_IN_FLIGHT = 3;
+/**
+ * Rows read per page by the platform sources.
+ *
+ * @stability stable
+ */
+exports.DEFAULT_EXPORT_PAGE_SIZE = 500;
+/**
+ * Storage rows the purge reads per batch.
+ *
+ * @stability stable
+ */
+exports.EXPORT_PURGE_BATCH = 200;
+//# sourceMappingURL=exports.constants.js.map

package/dist/exports/exports.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports.constants.js","sourceRoot":"","sources":["../../src/exports/exports.constants.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,6CAA6C;AAC7C,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,oEAAoE;AACpE,gFAAgF;;;AAIhF;;;;GAIG;AACU,QAAA,mBAAmB,GAAG,YAAY,CAAC;AAEhD;;;;GAIG;AACU,QAAA,qBAAqB,GAAG,cAAc,CAAC;AAEpD;;;;;GAKG;AACU,QAAA,wBAAwB,GAAG,MAAM,CAAC;AAE/C;;;;;GAKG;AACU,QAAA,uBAAuB,GAAG,cAAc,CAAC;AAEtD;;;;;;GAMG;AACU,QAAA,mBAAmB,GAAG,eAAe,CAAC;AAEnD;;;;GAIG;AACU,QAAA,mBAAmB,GAAG,QAAQ,CAAC;AAE5C;;;;;GAKG;AACU,QAAA,oBAAoB,GAAG,QAAQ,CAAC;AAE7C;;;;;;GAMG;AACU,QAAA,oBAAoB,GAAG,UAAU,CAAC;AAE/C;;;;GAIG;AACU,QAAA,wBAAwB,GAAG,gBAAgB,CAAC;AAEzD;;;;;;GAMG;AACU,QAAA,uBAAuB,GAAG,eAAe,CAAC;AAEvD;;;;;;GAMG;AACU,QAAA,oBAAoB,GAAmC,MAAM,CAAC,MAAM,CAAC;IAChF,MAAM,CAAC,MAAM,CAAC;QACZ,EAAE,EAAE,eAAe;QACnB,MAAM,EAAE,gCAAwB;QAChC,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,MAAe;QACtB,WAAW,EAAE,8FAA8F;KAC5G,CAAC;IACF,MAAM,CAAC,MAAM,CAAC;QACZ,EAAE,EAAE,cAAc;QAClB,MAAM,EAAE,+BAAuB;QAC/B,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,KAAc;QACrB,WAAW,EAAE,oGAAoG;KAClH,CAAC;CACH,CAAC,CAAC;AAEH;;;;GAIG;AACU,QAAA,6BAA6B,GAAG,CAAC,CAAC;AAE/C;;;;GAIG;AACU,QAAA,uCAAuC,GAAG,GAAG,CAAC;AAE3D;;;;GAIG;AACU,QAAA,4BAA4B,GAAG,CAAC,CAAC;AAE9C;;;;GAIG;AACU,QAAA,wBAAwB,GAAG,GAAG,CAAC;AAE5C;;;;GAIG;AACU,QAAA,kBAAkB,GAAG,GAAG,CAAC"}

package/dist/exports/exports.controller.d.ts

@@ -0,0 +1,147 @@
+import { type ExportListResponse, type ExportSourcesResponse, type ExportView } from '@marinoscar/platform-contract/exports';
+import type { Principal } from '../core/index';
+import { ExportsService } from './exports.service';
+declare const CreateExportDto_base: import("nestjs-zod").ZodDto<import("zod").ZodObject<{
+    source: import("zod").ZodString;
+    format: import("zod").ZodString;
+    request: import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+    orgId: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strict>, false>;
+/**
+ * `POST /api/exports` body.
+ *
+ * @stability experimental
+ */
+export declare class CreateExportDto extends CreateExportDto_base {
+}
+declare const ExportResponseDto_base: import("nestjs-zod").ZodDto<import("zod").ZodObject<{
+    id: import("zod").ZodString;
+    source: import("zod").ZodString;
+    format: import("zod").ZodString;
+    scope: import("zod").ZodEnum<import("@marinoscar/platform-contract/exports").ExportScopeEnum>;
+    orgId: import("zod").ZodNullable<import("zod").ZodString>;
+    status: import("zod").ZodEnum<import("@marinoscar/platform-contract/exports").ExportStatusEnum>;
+    createdAt: import("zod").ZodString;
+    completedAt: import("zod").ZodNullable<import("zod").ZodString>;
+    expiresAt: import("zod").ZodNullable<import("zod").ZodString>;
+    fileName: import("zod").ZodNullable<import("zod").ZodString>;
+    mimeType: import("zod").ZodNullable<import("zod").ZodString>;
+    sizeBytes: import("zod").ZodNullable<import("zod").ZodNumber>;
+    rowCounts: import("zod").ZodNullable<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>>;
+    error: import("zod").ZodNullable<import("zod").ZodString>;
+    download: import("zod").ZodNullable<import("zod").ZodObject<{
+        url: import("zod").ZodString;
+        expiresAt: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, false>;
+/**
+ * One export.
+ *
+ * @stability experimental
+ */
+export declare class ExportResponseDto extends ExportResponseDto_base {
+}
+declare const ExportListResponseDto_base: import("nestjs-zod").ZodDto<import("zod").ZodObject<{
+    items: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        source: import("zod").ZodString;
+        format: import("zod").ZodString;
+        scope: import("zod").ZodEnum<import("@marinoscar/platform-contract/exports").ExportScopeEnum>;
+        orgId: import("zod").ZodNullable<import("zod").ZodString>;
+        status: import("zod").ZodEnum<import("@marinoscar/platform-contract/exports").ExportStatusEnum>;
+        createdAt: import("zod").ZodString;
+        completedAt: import("zod").ZodNullable<import("zod").ZodString>;
+        expiresAt: import("zod").ZodNullable<import("zod").ZodString>;
+        fileName: import("zod").ZodNullable<import("zod").ZodString>;
+        mimeType: import("zod").ZodNullable<import("zod").ZodString>;
+        sizeBytes: import("zod").ZodNullable<import("zod").ZodNumber>;
+        rowCounts: import("zod").ZodNullable<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>>;
+        error: import("zod").ZodNullable<import("zod").ZodString>;
+        download: import("zod").ZodNullable<import("zod").ZodObject<{
+            url: import("zod").ZodString;
+            expiresAt: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, false>;
+/**
+ * `GET /api/exports`.
+ *
+ * @stability experimental
+ */
+export declare class ExportListResponseDto extends ExportListResponseDto_base {
+}
+declare const ExportSourcesResponseDto_base: import("nestjs-zod").ZodDto<import("zod").ZodObject<{
+    items: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        scope: import("zod").ZodEnum<import("@marinoscar/platform-contract/exports").ExportScopeEnum>;
+        label: import("zod").ZodString;
+        description: import("zod").ZodOptional<import("zod").ZodString>;
+        formats: import("zod").ZodArray<import("zod").ZodObject<{
+            id: import("zod").ZodString;
+            label: import("zod").ZodString;
+            extension: import("zod").ZodString;
+            mimeType: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+        fields: import("zod").ZodArray<import("zod").ZodObject<{
+            key: import("zod").ZodString;
+            label: import("zod").ZodString;
+            kind: import("zod").ZodEnum<import("@marinoscar/platform-contract/exports").ExportRequestFieldKindEnum>;
+            required: import("zod").ZodBoolean;
+            description: import("zod").ZodOptional<import("zod").ZodString>;
+            options: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+                value: import("zod").ZodString;
+                label: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>>>;
+            default: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodBoolean]>>;
+        }, import("zod/v4/core").$strip>>;
+        crossOrg: import("zod").ZodBoolean;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, false>;
+/**
+ * `GET /api/exports/sources`.
+ *
+ * @stability experimental
+ */
+export declare class ExportSourcesResponseDto extends ExportSourcesResponseDto_base {
+}
+/**
+ * The export routes. See the file header.
+ *
+ * @stability experimental
+ */
+export declare class ExportsController {
+    private readonly exports;
+    constructor(exports: ExportsService);
+    /**
+     * The sources and formats the caller may use.
+     *
+     * @param user - the caller.
+     * @returns the sources.
+     */
+    sources(user: Principal | undefined): ExportSourcesResponse;
+    /**
+     * Queues an export.
+     *
+     * @param user - the caller.
+     * @param body - the request.
+     * @returns the export, `pending`.
+     */
+    create(user: Principal | undefined, body: CreateExportDto): Promise<ExportView>;
+    /**
+     * The caller's recent exports.
+     *
+     * @param user - the caller.
+     * @returns the exports.
+     */
+    list(user: Principal | undefined): Promise<ExportListResponse>;
+    /**
+     * One export, with a fresh signed download while ready.
+     *
+     * @param user - the caller.
+     * @param id - the export id.
+     * @returns the export.
+     */
+    get(user: Principal | undefined, id: string): Promise<ExportView>;
+}
+export {};
+//# sourceMappingURL=exports.controller.d.ts.map

package/dist/exports/exports.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports.controller.d.ts","sourceRoot":"","sources":["../../src/exports/exports.controller.ts"],"names":[],"mappings":"AAaA,OAAO,EAOL,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EAChB,MAAM,uCAAuC,CAAC;AAI/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAwB,MAAM,mBAAmB,CAAC;;;;;;;AAEzE;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,oBAAgC;CAAG;;;;;;;;;;;;;;;;;;;;;AAExE;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,sBAA0B;CAAG;;;;;;;;;;;;;;;;;;;;;;;AAEpE;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,0BAAsC;CAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEpF;;;;GAIG;AACH,qBAAa,wBAAyB,SAAQ,6BAAyC;CAAG;AAS1F;;;;GAIG;AACH,qBAEa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD;;;;;OAKG;IAWH,OAAO,CAAqB,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,qBAAqB;IAI/E;;;;;;OAMG;IAkBH,MAAM,CAAqB,IAAI,EAAE,SAAS,GAAG,SAAS,EAAU,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAI3G;;;;;OAKG;IAQH,IAAI,CAAqB,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIlF;;;;;;OAMG;IAaH,GAAG,CAAqB,IAAI,EAAE,SAAS,GAAG,SAAS,EAA8B,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAGlH"}