@antelopejs/interface-dms 0.3.5 → 0.4.0

package/dist/base/display.d.ts

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import type { EnumOption } from "./types/enum-option";
+import { HttpMethod } from "./types/http";
+import { type Tone } from "./types/tone";
+/** The button variants a block link action may take. */
+export declare const BLOCK_ACTION_VARIANTS: readonly ["solid", "outline", "soft", "subtle", "ghost", "link"];
+export type BlockActionVariant = (typeof BLOCK_ACTION_VARIANTS)[number];
+/**
+ * A link button a display block renders. `to` is a DMS route, an `#anchor` on
+ * the page, or an absolute URL (opened in a new tab). The block picks the look
+ * of the buttons by their place; `variant` and `color` override it.
+ */
+export interface BlockLinkAction {
+    /** Button text; `$`-prefixed for an i18n key. */
+    label: string;
+    to: string;
+    icon?: string;
+    variant?: BlockActionVariant;
+    color?: Tone;
+}
+export declare const BlockLinkActionSchema: z.ZodObject<{
+    label: z.ZodString;
+    to: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+    variant: z.ZodOptional<z.ZodEnum<["solid", "outline", "soft", "subtle", "ghost", "link"]>>;
+    color: z.ZodOptional<z.ZodEnum<["primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral", ...("primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral")[]]>>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    to: string;
+    icon?: string | undefined;
+    variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+    color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+}, {
+    label: string;
+    to: string;
+    icon?: string | undefined;
+    variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+    color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+}>;
+/** The link buttons option of a display block. */
+export declare const blockActionsOption: (description: string) => z.ZodOptional<z.ZodArray<z.ZodObject<{
+    label: z.ZodString;
+    to: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+    variant: z.ZodOptional<z.ZodEnum<["solid", "outline", "soft", "subtle", "ghost", "link"]>>;
+    color: z.ZodOptional<z.ZodEnum<["primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral", ...("primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral")[]]>>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    to: string;
+    icon?: string | undefined;
+    variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+    color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+}, {
+    label: string;
+    to: string;
+    icon?: string | undefined;
+    variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+    color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+}>, "many">>;
+/** What a block shows when it has nothing to list. */
+export interface BlockEmptyText {
+    /** `$`-prefixed for an i18n key, like `description`. */
+    title: string;
+    description?: string;
+}
+/** The `empty` option of a block. */
+export declare const blockEmptyOption: () => z.ZodOptional<z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    description?: string | undefined;
+}, {
+    title: string;
+    description?: string | undefined;
+}>>;
+/**
+ * The `card` option of a block: the card surface around it, `isOnByDefault`
+ * or not. Turn it off to nest the block in a `Card`.
+ */
+export declare const blockCardOption: (isOnByDefault: boolean) => z.ZodDefault<z.ZodBoolean>;
+/** The `fetchUrl` option of a block, picked in the editor's source list. */
+export declare const blockFetchUrlOption: (description: string) => z.ZodOptional<z.ZodString>;
+/** The `fetchUrlMethod` option that goes with `fetchUrl`. */
+export declare const blockFetchUrlMethodOption: () => z.ZodOptional<z.ZodNativeEnum<typeof HttpMethod>>;
+/**
+ * The options a list block (StatGroup, KeyValueList, NavCardGrid,
+ * ActivityFeed) reads its items from a route with. The route answers
+ * `{ items: [...] }` in the block's own item shape, which replaces the static
+ * `items`.
+ */
+export interface BlockItemsSource {
+    fetchUrl?: string;
+    fetchUrlMethod?: EnumOption<HttpMethod>;
+    /** Shown when there is nothing to list. */
+    empty?: BlockEmptyText;
+    /**
+     * How many placeholder rows, cells or cards the block draws while
+     * `fetchUrl` loads. The block cannot know the length of a list it has not
+     * read yet: set it to the length the route usually answers, so the block
+     * keeps its height when the items land. A count, not a height, so it holds
+     * at every width.
+     *
+     * Optional. Defaults to `columns`, or 4 (StatGroup); 5 (KeyValueList);
+     * `columns`, or 3 (NavCardGrid); `maxItems`, or 3 (ActivityFeed).
+     */
+    skeletonCount?: number;
+}
+/** The options of `BlockItemsSource`, for a list block's schema. */
+export declare const blockItemsSourceOptions: () => {
+    fetchUrl: z.ZodOptional<z.ZodString>;
+    fetchUrlMethod: z.ZodOptional<z.ZodNativeEnum<typeof HttpMethod>>;
+    empty: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        description?: string | undefined;
+    }, {
+        title: string;
+        description?: string | undefined;
+    }>>;
+    skeletonCount: z.ZodOptional<z.ZodNumber>;
+};

package/dist/base/display.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blockItemsSourceOptions = exports.blockFetchUrlMethodOption = exports.blockFetchUrlOption = exports.blockCardOption = exports.blockEmptyOption = exports.blockActionsOption = exports.BlockLinkActionSchema = exports.BLOCK_ACTION_VARIANTS = void 0;
+const zod_1 = require("zod");
+const block_registry_1 = require("./block-registry");
+const http_1 = require("./types/http");
+const tone_1 = require("./types/tone");
+const display_1 = require("./internal/display");
+/** The button variants a block link action may take. */
+exports.BLOCK_ACTION_VARIANTS = [
+    "solid",
+    "outline",
+    "soft",
+    "subtle",
+    "ghost",
+    "link",
+];
+exports.BlockLinkActionSchema = zod_1.z.object({
+    label: (0, block_registry_1.ui)(zod_1.z.string().describe("Button text."), { label: "Label" }),
+    to: (0, block_registry_1.ui)(zod_1.z.string().describe("Route, `#anchor` or absolute URL."), {
+        label: "Link",
+        widget: "url",
+    }),
+    icon: (0, block_registry_1.ui)(zod_1.z.string().optional(), { label: "Icon", widget: "icon" }),
+    variant: (0, block_registry_1.ui)(zod_1.z.enum(exports.BLOCK_ACTION_VARIANTS).optional(), {
+        label: "Variant",
+        widget: "select",
+    }),
+    color: (0, block_registry_1.ui)((0, display_1.toneEnum)(tone_1.TONES).optional(), {
+        label: "Colour",
+        widget: "select",
+    }),
+});
+/** The link buttons option of a display block. */
+const blockActionsOption = (description) => (0, block_registry_1.ui)(zod_1.z.array(exports.BlockLinkActionSchema).optional().describe(description), {
+    label: "Actions",
+    group: "content",
+});
+exports.blockActionsOption = blockActionsOption;
+/** The `empty` option of a block. */
+const blockEmptyOption = () => (0, block_registry_1.ui)(zod_1.z
+    .object({
+    title: (0, block_registry_1.ui)(zod_1.z.string(), { label: "Title" }),
+    description: (0, block_registry_1.ui)(zod_1.z.string().optional(), {
+        label: "Description",
+        widget: "textarea",
+    }),
+})
+    .optional()
+    .describe("Shown when there is nothing to list."), { label: "Empty state", group: "content" });
+exports.blockEmptyOption = blockEmptyOption;
+/**
+ * The `card` option of a block: the card surface around it, `isOnByDefault`
+ * or not. Turn it off to nest the block in a `Card`.
+ */
+const blockCardOption = (isOnByDefault) => (0, block_registry_1.ui)(zod_1.z
+    .boolean()
+    .default(isOnByDefault)
+    .describe("Card surface around the block; off inside a `Card`."), { label: "In a card", group: "appearance", widget: "switch" });
+exports.blockCardOption = blockCardOption;
+/** The `fetchUrl` option of a block, picked in the editor's source list. */
+const blockFetchUrlOption = (description) => (0, block_registry_1.ui)(zod_1.z.string().optional().describe(description), {
+    label: "Data source",
+    group: "data",
+    widget: "dataSource",
+    advanced: true,
+});
+exports.blockFetchUrlOption = blockFetchUrlOption;
+/** The `fetchUrlMethod` option that goes with `fetchUrl`. */
+const blockFetchUrlMethodOption = () => (0, block_registry_1.ui)(zod_1.z.nativeEnum(http_1.HttpMethod).optional(), {
+    label: "HTTP method",
+    group: "advanced",
+    widget: "select",
+});
+exports.blockFetchUrlMethodOption = blockFetchUrlMethodOption;
+/** The options of `BlockItemsSource`, for a list block's schema. */
+const blockItemsSourceOptions = () => ({
+    fetchUrl: (0, exports.blockFetchUrlOption)("Route answering `{ items }`; when set it replaces the static items."),
+    fetchUrlMethod: (0, exports.blockFetchUrlMethodOption)(),
+    empty: (0, exports.blockEmptyOption)(),
+    skeletonCount: (0, block_registry_1.ui)(zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Placeholder items drawn while the data source loads."), {
+        label: "Loading placeholders",
+        group: "data",
+        widget: "number",
+        min: 1,
+        advanced: true,
+    }),
+});
+exports.blockItemsSourceOptions = blockItemsSourceOptions;
+//# sourceMappingURL=display.js.map

package/dist/base/display.js.map

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

package/dist/base/empty-state.d.ts

@@ -0,0 +1,106 @@
+import { ComponentBuilder } from "../component";
+import { z } from "zod";
+import type { BaseComponentProps } from "./types";
+import { type BlockLinkAction } from "./display";
+import { type Tone } from "./types/tone";
+/** Why a block is empty: see `EmptyStateVariant`. */
+export declare const EMPTY_STATE_VARIANTS: readonly ["no-data", "no-result", "no-access", "error"];
+/** Why it is empty: sets the default icon, the well tone and the live role. */
+export type EmptyStateVariant = (typeof EMPTY_STATE_VARIANTS)[number];
+/** The sizes of an empty state. */
+export declare const EMPTY_STATE_SIZES: readonly ["sm", "md", "lg"];
+export type EmptyStateSize = (typeof EMPTY_STATE_SIZES)[number];
+/** The options `EmptyState` takes. */
+export interface EmptyStateProps extends BaseComponentProps {
+    /** `$`-prefixed for an i18n key, like every text of the block. */
+    title: string;
+    description?: string;
+    variant?: EmptyStateVariant;
+    /** Overrides the variant's icon. */
+    icon?: string;
+    /** Overrides the variant's well tone. */
+    tone?: Tone;
+    /** Hatched panel behind the content. */
+    hatched?: boolean;
+    size?: EmptyStateSize;
+    actions?: BlockLinkAction[];
+    /** Card surface around it; turn it off inside a `Card` block. */
+    card?: boolean;
+}
+/**
+ * EmptyState — an icon well, a title, a short explanation and the actions
+ * that fit the case: a first-run page, a section with nothing in it yet, a
+ * page the viewer cannot use.
+ *
+ * @example
+ * ```typescript
+ * EmptyState({
+ *   title: "No invoices yet",
+ *   description: "Invoices appear here once a customer is billed.",
+ *   actions: [{ label: "Create an invoice", to: "/sales/invoices/new" }],
+ * })
+ * ```
+ */
+export declare function EmptyState(options: EmptyStateProps): ComponentBuilder<EmptyStateProps>;
+/** The options `EmptyState` accepts. */
+export declare const EmptyStateSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        to: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        variant: z.ZodOptional<z.ZodEnum<["solid", "outline", "soft", "subtle", "ghost", "link"]>>;
+        color: z.ZodOptional<z.ZodEnum<["primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral", ...("primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral")[]]>>;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        to: string;
+        icon?: string | undefined;
+        variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+        color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }, {
+        label: string;
+        to: string;
+        icon?: string | undefined;
+        variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+        color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }>, "many">>;
+    variant: z.ZodDefault<z.ZodEnum<["no-data", "no-result", "no-access", "error"]>>;
+    icon: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodEnum<["primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral", ...("primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral")[]]>>;
+    size: z.ZodDefault<z.ZodEnum<["sm", "md", "lg"]>>;
+    hatched: z.ZodOptional<z.ZodBoolean>;
+    card: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    size: "sm" | "md" | "lg";
+    title: string;
+    variant: "error" | "no-data" | "no-result" | "no-access";
+    card: boolean;
+    description?: string | undefined;
+    icon?: string | undefined;
+    actions?: {
+        label: string;
+        to: string;
+        icon?: string | undefined;
+        variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+        color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }[] | undefined;
+    tone?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    hatched?: boolean | undefined;
+}, {
+    title: string;
+    description?: string | undefined;
+    size?: "sm" | "md" | "lg" | undefined;
+    icon?: string | undefined;
+    variant?: "error" | "no-data" | "no-result" | "no-access" | undefined;
+    card?: boolean | undefined;
+    actions?: {
+        label: string;
+        to: string;
+        icon?: string | undefined;
+        variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+        color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }[] | undefined;
+    tone?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    hatched?: boolean | undefined;
+}>;

package/dist/base/empty-state.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmptyStateSchema = exports.EMPTY_STATE_SIZES = exports.EMPTY_STATE_VARIANTS = void 0;
+exports.EmptyState = EmptyState;
+const component_1 = require("../component");
+const zod_1 = require("zod");
+const block_registry_1 = require("./block-registry");
+const display_1 = require("./display");
+const display_2 = require("./internal/display");
+const tone_1 = require("./types/tone");
+/** Why a block is empty: see `EmptyStateVariant`. */
+exports.EMPTY_STATE_VARIANTS = [
+    "no-data",
+    "no-result",
+    "no-access",
+    "error",
+];
+/** The sizes of an empty state. */
+exports.EMPTY_STATE_SIZES = ["sm", "md", "lg"];
+const EMPTY_STATE_COMPONENT_NAME = "dms-empty-state-block";
+const EMPTY_STATE_ICON = "i-ph-tray";
+const EMPTY_STATE_DEFAULTS = {
+    variant: "no-data",
+    size: "md",
+    card: true,
+};
+/**
+ * EmptyState — an icon well, a title, a short explanation and the actions
+ * that fit the case: a first-run page, a section with nothing in it yet, a
+ * page the viewer cannot use.
+ *
+ * @example
+ * ```typescript
+ * EmptyState({
+ *   title: "No invoices yet",
+ *   description: "Invoices appear here once a customer is billed.",
+ *   actions: [{ label: "Create an invoice", to: "/sales/invoices/new" }],
+ * })
+ * ```
+ */
+function EmptyState(options) {
+    return new component_1.ComponentBuilder(EMPTY_STATE_COMPONENT_NAME)
+        .options({ ...EMPTY_STATE_DEFAULTS, ...options })
+        .meta({
+        name: options.title || "Empty state",
+        icon: options.icon || EMPTY_STATE_ICON,
+    });
+}
+/** The options `EmptyState` accepts. */
+exports.EmptyStateSchema = zod_1.z.object({
+    title: (0, block_registry_1.ui)(zod_1.z.string().describe("Title of the empty state."), {
+        label: "Title",
+        group: "content",
+        initial: "Nothing here yet",
+    }),
+    description: (0, block_registry_1.ui)(zod_1.z.string().optional(), {
+        label: "Description",
+        group: "content",
+        widget: "textarea",
+    }),
+    actions: (0, display_1.blockActionsOption)("Buttons under the text; the first one leads."),
+    variant: (0, block_registry_1.ui)(zod_1.z
+        .enum(exports.EMPTY_STATE_VARIANTS)
+        .default(EMPTY_STATE_DEFAULTS.variant)
+        .describe("Why it is empty; sets the icon and the tone."), {
+        label: "Variant",
+        group: "appearance",
+        widget: "select",
+        valueLabels: {
+            "no-data": "No data yet",
+            "no-result": "No result",
+            "no-access": "No access",
+            error: "Error",
+        },
+    }),
+    icon: (0, block_registry_1.ui)(zod_1.z.string().optional().describe("Overrides the variant's icon."), {
+        label: "Icon",
+        group: "appearance",
+        widget: "icon",
+    }),
+    tone: (0, block_registry_1.ui)((0, display_2.toneEnum)(tone_1.TONES).optional(), {
+        label: "Tone",
+        group: "appearance",
+        widget: "select",
+    }),
+    size: (0, block_registry_1.ui)(zod_1.z.enum(exports.EMPTY_STATE_SIZES).default(EMPTY_STATE_DEFAULTS.size), {
+        label: "Size",
+        group: "appearance",
+        widget: "segmented",
+    }),
+    hatched: (0, block_registry_1.ui)(zod_1.z.boolean().optional().describe("Hatched panel behind it."), {
+        label: "Hatched",
+        group: "appearance",
+        widget: "switch",
+    }),
+    card: (0, display_1.blockCardOption)(EMPTY_STATE_DEFAULTS.card),
+});
+(0, block_registry_1.RegisterBlockType)({
+    type: "EmptyState",
+    componentName: EMPTY_STATE_COMPONENT_NAME,
+    schema: exports.EmptyStateSchema,
+    meta: {
+        name: "Empty state",
+        icon: EMPTY_STATE_ICON,
+        description: "Says why there is nothing here, and what to do next.",
+        group: "content",
+    },
+});
+//# sourceMappingURL=empty-state.js.map

package/dist/base/empty-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty-state.js","sourceRoot":"","sources":["../../src/base/empty-state.ts"],"names":[],"mappings":"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"}

package/dist/base/export-jobs.d.ts

@@ -1,10 +1,20 @@
+/**
+ * The export-job contract.
+ *
+ * Running an export is DMS behaviour -- it writes database rows, spools files
+ * through temporary storage, zips and mails them -- so the module implements it
+ * and this file only declares what a caller needs: the vocabulary, the
+ * defaults, and the entry points. Everything the engine uses on the way
+ * (storage upload, stale sweeps, filename building) stays inside the module.
+ */
 import type { RequestContext } from "@antelopejs/interface-api";
 import type { User } from "../auth/db";
 import type { ExportJob } from "../db/tables/exportJobs.table";
 import type { ExportStatus } from "./types/export-status";
+/** Lifetime of a stored export, enforced by the `sweep-stale-exports` cron. */
 export declare const EXPORT_TTL_MS = 86400000;
+/** Query parameter carrying the job id on a delivered download link. */
 export declare const EXPORT_JOB_QUERY_PARAM = "exportJob";
-export declare const DEFAULT_EXPORT_HISTORY_LIMIT = 20;
 export declare const DEFAULT_EXPORT_FORMAT = "csv";
 export declare const DEFAULT_DELIVERY = "download";
 export declare const EMAIL_DELIVERY = "email";
@@ -23,18 +33,22 @@ export interface Exporter {
     createWriter(filePath: string): ExportWriter;
 }
 export interface ExportJobFailure {
+    /** Part of the export that failed, e.g. a contributing module id. */
     source: string;
     error: string;
 }
+/** Result a `generate` implementation returns to report an incomplete export. */
 export interface ExportJobResultSummary {
     partial: boolean;
     failures: ExportJobFailure[];
 }
 export interface ExportJobDeliveryOptions {
     delivery: string;
+    /** Client-side path the delivered link points to. */
     deliveryPath?: string;
 }
 export interface Deliverer {
+    /** Called when the job is created, so an unusable delivery fails fast. */
     validate?(options: ExportJobDeliveryOptions): void;
     deliver(exportRecord: ExportJob, resultPath: string): Promise<void>;
 }
@@ -44,6 +58,7 @@ export interface ExportJobGenerateContext<TContext = unknown> {
     localPath: string;
     context: TContext;
     reportProgress: (progress: number) => Promise<void>;
+    /** Aborted when the job exceeds `maxExecutionTimeMs`. */
     signal: AbortSignal;
 }
 export interface RunExportJobOptions<TContext = unknown> {
@@ -55,12 +70,25 @@ export interface RunExportJobOptions<TContext = unknown> {
     extension: string;
     contentType: string;
     delivery?: string;
+    /** Client-side path a delivered link points to, required by email delivery. */
     deliveryPath?: string;
+    /**
+     * Keeps the record and its stored file after a download, until the stale
+     * export sweep expires them. Required for scopes exposing a job history or a
+     * delivered link, which both outlive the first download.
+     */
     retainUntilExpiry?: boolean;
+    /** Defaults to 10 minutes. Job is marked failed if `generate` exceeds this. */
     maxExecutionTimeMs?: number;
+    /**
+     * A returned summary is stored on the job and surfaced to its consumers.
+     * `void` rather than `undefined`, which would reject the generators that
+     * report no summary.
+     */
     generate: (ctx: ExportJobGenerateContext<TContext>) => Promise<ExportJobResultSummary | void>;
 }
 export interface ExportJobOwnership<TContext = unknown> {
+    /** Optional extra ACL beyond the userId check. */
     isOwnedBy?: (record: ExportJob, context: TContext, user: User) => boolean;
 }
 export interface ExportJobAccessOptions<TContext = unknown> extends ExportJobOwnership<TContext> {
@@ -77,7 +105,9 @@ export interface ExportJobStatus {
     error?: string;
     filename?: string;
     extension?: string;
+    /** Present once completed: reports whether parts of the export are missing. */
     result?: ExportJobResultSummary;
+    /** When the stale export sweep drops the job and its stored file. */
     expiresAt?: Date;
 }
 export interface ExportJobSummary extends ExportJobStatus {
@@ -89,9 +119,17 @@ export interface ListExportJobsOptions {
     scope?: string;
     limit?: number;
 }
+/** Looks up an export format by id; the DMS ships `csv`. */
 export declare const getExporter: (format: string) => Promise<Exporter>;
+/** Looks up a delivery mode by id; the DMS ships `download` and `email`. */
 export declare const getDeliverer: (delivery: string) => Promise<Deliverer>;
+/** Starts an export job and returns the ticket its caller polls. */
 export declare function runExportJob<TContext = unknown>(options: RunExportJobOptions<TContext>): Promise<ExportJobTicket>;
 export declare function getExportJobStatus<TContext = unknown>(ctx: RequestContext, user: User, jobId: string, access?: ExportJobAccessOptions<TContext>): Promise<ExportJobStatus>;
+/**
+ * Streams a completed export job to the response. Returns once the pipe is
+ * started, not once it has drained.
+ */
 export declare function downloadExportJob<TContext = unknown>(ctx: RequestContext, user: User, jobId: string, access?: ExportJobAccessOptions<TContext>): Promise<void>;
+/** Lists the caller's own export jobs, most recent first. */
 export declare const listExportJobs: (ctx: RequestContext, user: User, options?: ListExportJobsOptions | undefined) => Promise<ExportJobSummary[]>;

package/dist/base/export-jobs.js

@@ -1,30 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listExportJobs = exports.getDeliverer = exports.getExporter = exports.EMAIL_DELIVERY = exports.DEFAULT_DELIVERY = exports.DEFAULT_EXPORT_FORMAT = exports.DEFAULT_EXPORT_HISTORY_LIMIT = exports.EXPORT_JOB_QUERY_PARAM = exports.EXPORT_TTL_MS = void 0;
+exports.listExportJobs = exports.getDeliverer = exports.getExporter = exports.EMAIL_DELIVERY = exports.DEFAULT_DELIVERY = exports.DEFAULT_EXPORT_FORMAT = exports.EXPORT_JOB_QUERY_PARAM = exports.EXPORT_TTL_MS = void 0;
 exports.runExportJob = runExportJob;
 exports.getExportJobStatus = getExportJobStatus;
 exports.downloadExportJob = downloadExportJob;
 const interface_core_1 = require("@antelopejs/interface-core");
-const time_1 = require("../utils/time");
+const time_1 = require("../utils/internal/time");
+/** Lifetime of a stored export, enforced by the `sweep-stale-exports` cron. */
 exports.EXPORT_TTL_MS = time_1.MILLISECONDS_PER_DAY;
+/** Query parameter carrying the job id on a delivered download link. */
 exports.EXPORT_JOB_QUERY_PARAM = "exportJob";
-exports.DEFAULT_EXPORT_HISTORY_LIMIT = 20;
 exports.DEFAULT_EXPORT_FORMAT = "csv";
 exports.DEFAULT_DELIVERY = "download";
 exports.EMAIL_DELIVERY = "email";
+/** Looks up an export format by id; the DMS ships `csv`. */
 exports.getExporter = (0, interface_core_1.InterfaceFunction)();
+/** Looks up a delivery mode by id; the DMS ships `download` and `email`. */
 exports.getDeliverer = (0, interface_core_1.InterfaceFunction)();
 const runExportJobProxy = (0, interface_core_1.InterfaceFunction)();
 const getExportJobStatusProxy = (0, interface_core_1.InterfaceFunction)();
 const downloadExportJobProxy = (0, interface_core_1.InterfaceFunction)();
+/** Starts an export job and returns the ticket its caller polls. */
 function runExportJob(options) {
     return runExportJobProxy(options);
 }
 function getExportJobStatus(ctx, user, jobId, access) {
     return getExportJobStatusProxy(ctx, user, jobId, access);
 }
+/**
+ * Streams a completed export job to the response. Returns once the pipe is
+ * started, not once it has drained.
+ */
 function downloadExportJob(ctx, user, jobId, access) {
     return downloadExportJobProxy(ctx, user, jobId, access);
 }
+/** Lists the caller's own export jobs, most recent first. */
 exports.listExportJobs = (0, interface_core_1.InterfaceFunction)();
 //# sourceMappingURL=export-jobs.js.map

package/dist/base/export-jobs.js.map

@@ -1 +1 @@
-{"version":3,"file":"export-jobs.js","sourceRoot":"","sources":["../../src/base/export-jobs.ts"],"names":[],"mappings":";;;AAwMA,oCAIC;AAED,gDAOC;AAMD,8CAOC;AAxND,+DAA+D;AAG/D,wCAAqD;AAIxC,QAAA,aAAa,GAAG,2BAAoB,CAAC;AAGrC,QAAA,sBAAsB,GAAG,WAAW,CAAC;AAErC,QAAA,4BAA4B,GAAG,EAAE,CAAC;AAClC,QAAA,qBAAqB,GAAG,KAAK,CAAC;AAC9B,QAAA,gBAAgB,GAAG,UAAU,CAAC;AAC9B,QAAA,cAAc,GAAG,OAAO,CAAC;AA2HzB,QAAA,WAAW,GAAG,IAAA,kCAAiB,GAAgC,CAAC;AAGhE,QAAA,YAAY,GACvB,IAAA,kCAAiB,GAAmC,CAAC;AAwBvD,MAAM,iBAAiB,GACrB,IAAA,kCAAiB,GAA2D,CAAC;AAE/E,MAAM,uBAAuB,GAC3B,IAAA,kCAAiB,GAOd,CAAC;AAEN,MAAM,sBAAsB,GAC1B,IAAA,kCAAiB,GAOd,CAAC;AAGN,SAAgB,YAAY,CAC1B,OAAsC;IAEtC,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAED,SAAgB,kBAAkB,CAChC,GAAmB,EACnB,IAAU,EACV,KAAa,EACb,MAAyC;IAEzC,OAAO,uBAAuB,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAC3D,CAAC;AAMD,SAAgB,iBAAiB,CAC/B,GAAmB,EACnB,IAAU,EACV,KAAa,EACb,MAAyC;IAEzC,OAAO,sBAAsB,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAC1D,CAAC;AAGY,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC"}
+{"version":3,"file":"export-jobs.js","sourceRoot":"","sources":["../../src/base/export-jobs.ts"],"names":[],"mappings":";;;AAsMA,oCAIC;AAED,gDAOC;AAMD,8CAOC;AAtND,+DAA+D;AAG/D,iDAA8D;AAG9D,+EAA+E;AAClE,QAAA,aAAa,GAAG,2BAAoB,CAAC;AAElD,wEAAwE;AAC3D,QAAA,sBAAsB,GAAG,WAAW,CAAC;AACrC,QAAA,qBAAqB,GAAG,KAAK,CAAC;AAC9B,QAAA,gBAAgB,GAAG,UAAU,CAAC;AAC9B,QAAA,cAAc,GAAG,OAAO,CAAC;AA0HtC,4DAA4D;AAC/C,QAAA,WAAW,GAAG,IAAA,kCAAiB,GAAgC,CAAC;AAE7E,4EAA4E;AAC/D,QAAA,YAAY,GACvB,IAAA,kCAAiB,GAAmC,CAAC;AAwBvD,MAAM,iBAAiB,GACrB,IAAA,kCAAiB,GAA2D,CAAC;AAE/E,MAAM,uBAAuB,GAC3B,IAAA,kCAAiB,GAOd,CAAC;AAEN,MAAM,sBAAsB,GAC1B,IAAA,kCAAiB,GAOd,CAAC;AAEN,oEAAoE;AACpE,SAAgB,YAAY,CAC1B,OAAsC;IAEtC,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AAED,SAAgB,kBAAkB,CAChC,GAAmB,EACnB,IAAU,EACV,KAAa,EACb,MAAyC;IAEzC,OAAO,uBAAuB,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAC/B,GAAmB,EACnB,IAAU,EACV,KAAa,EACb,MAAyC;IAEzC,OAAO,sBAAsB,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAC1D,CAAC;AAED,6DAA6D;AAChD,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC"}