@sudobility/screenwriter_types 0.1.1

package/dist/io/index.d.ts

@@ -0,0 +1,395 @@
+import { z } from 'zod';
+import type { ConversionReport } from '../formats/index.js';
+/**
+ * Imports, exports and batch watermark as jobs, plus the upload port they share (slice B16; spec 05 §6.18, §6.1 `uploads`,
+ * §13). The synchronous `POST /projects/:pid/documents/import`, `POST /documents/:did/export` and `GET /formats` (see
+ * `formats/`) stay until the app migrates.
+ *
+ * Formats are exactly what `writing_formats` has today: import Fountain, FDX and Fade In; export Fountain, FDX and the plain
+ * JSON backup. PDF, DOCX, Celtx, Scrivener and OCR answer `IMPORT_FORMAT_UNSUPPORTED` / `EXPORT_FORMAT_UNSUPPORTED` /
+ * `OCR_UNAVAILABLE`; nothing fakes them.
+ */
+/** Formats `POST /imports` accepts (a job kind `import.<format>` exists for each). */
+export declare const JOB_IMPORT_FORMATS: readonly ["fountain", "fdx", "fadein"];
+export type JobImportFormat = (typeof JOB_IMPORT_FORMATS)[number];
+/** Formats an export job produces (`export.<format>`). */
+export declare const JOB_EXPORT_FORMATS: readonly ["fountain", "fdx", "json"];
+export type JobExportFormat = (typeof JOB_EXPORT_FORMATS)[number];
+/** `POST /documents/export-combined` takes these (spec 05: pdf, fdx, fountain; pdf is not built). */
+export declare const COMBINED_EXPORT_FORMATS: readonly ["fdx", "fountain"];
+/** At most this many documents in one combined export (the job's `sources` cap). */
+export declare const COMBINED_EXPORT_MAX_DOCUMENTS = 20;
+/** At most this many recipients in one batch watermark (spec 05 §6.18). */
+export declare const BATCH_WATERMARK_MAX_RECIPIENTS = 500;
+export declare const UPLOAD_PURPOSES: readonly ["state", "watermark_lookup", "import"];
+export type UploadPurpose = (typeof UPLOAD_PURPOSES)[number];
+/**
+ * `POST /uploads/state`. `purpose` defaults to `state` (a Yjs state blob); `watermark_lookup` is a leaked file for
+ * `POST /workspaces/:wid/watermark-lookup`. `import` uploads are created by `POST /imports`, never here.
+ */
+export declare const uploadStateRequestSchema: z.ZodObject<{
+    sizeBytes: z.ZodNumber;
+    sha256Hex: z.ZodString;
+    purpose: z.ZodDefault<z.ZodEnum<{
+        state: "state";
+        watermark_lookup: "watermark_lookup";
+    }>>;
+}, z.core.$strip>;
+export type UploadStateRequest = z.input<typeof uploadStateRequestSchema>;
+/** A presigned PUT: send the bytes with `PUT url` (no `Authorization`), then use `uploadKey`. */
+export interface UploadStateResponse {
+    uploadKey: string;
+    url: string;
+    /** When the PUT url stops working (`SIGNED_URL_TTL_S`). */
+    expiresAt: string;
+}
+export declare const importOptionsSchema: z.ZodObject<{
+    templateId: z.ZodOptional<z.ZodString>;
+    ocr: z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
+        force: "force";
+        off: "off";
+    }>>;
+    ocrLanguage: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        outline: "outline";
+        script: "script";
+        bible: "bible";
+        treatment: "treatment";
+        other: "other";
+    }>>;
+    language: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ImportOptions = z.input<typeof importOptionsSchema>;
+/** `POST /imports`: one of `targetProjectId` (import as a new document) or `templateTarget` (a template file, `POST /templates/import {importId}`). */
+export declare const importCreateSchema: z.ZodObject<{
+    filename: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    sha256Hex: z.ZodString;
+    format: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodObject<{
+        templateId: z.ZodOptional<z.ZodString>;
+        ocr: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            force: "force";
+            off: "off";
+        }>>;
+        ocrLanguage: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            outline: "outline";
+            script: "script";
+            bible: "bible";
+            treatment: "treatment";
+            other: "other";
+        }>>;
+        language: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    targetProjectId: z.ZodOptional<z.ZodString>;
+    templateTarget: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodEnum<{
+            workspace: "workspace";
+            user: "user";
+        }>;
+        workspaceId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ImportCreateRequest = z.input<typeof importCreateSchema>;
+/** `POST /documents/:did/import-over`: the document is the route's. */
+export declare const importOverSchema: z.ZodObject<{
+    filename: z.ZodString;
+    sizeBytes: z.ZodNumber;
+    sha256Hex: z.ZodString;
+    format: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodObject<{
+        templateId: z.ZodOptional<z.ZodString>;
+        ocr: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            force: "force";
+            off: "off";
+        }>>;
+        ocrLanguage: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            outline: "outline";
+            script: "script";
+            bible: "bible";
+            treatment: "treatment";
+            other: "other";
+        }>>;
+        language: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ImportOverRequest = z.input<typeof importOverSchema>;
+/** Both answer this: PUT the file to `upload.url`, then `POST /imports/:importId/start`. No job exists yet. */
+export interface ImportCreateResponse {
+    importId: string;
+    upload: {
+        url: string;
+        expiresAt: string;
+    };
+}
+/** Input stored on `import.<format>` jobs (spec 05 §13). `newDocumentId` is minted at start so a retried run cannot make two documents. */
+export declare const importJobInputSchema: z.ZodObject<{
+    importId: z.ZodString;
+    targetProjectId: z.ZodString;
+    newDocumentId: z.ZodString;
+    filename: z.ZodString;
+    options: z.ZodOptional<z.ZodObject<{
+        templateId: z.ZodOptional<z.ZodString>;
+        ocr: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            force: "force";
+            off: "off";
+        }>>;
+        ocrLanguage: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            outline: "outline";
+            script: "script";
+            bible: "bible";
+            treatment: "treatment";
+            other: "other";
+        }>>;
+        language: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ImportJobInput = z.infer<typeof importJobInputSchema>;
+/** Input stored on `doc.importOver` jobs. */
+export declare const importOverJobInputSchema: z.ZodObject<{
+    importId: z.ZodString;
+    documentId: z.ZodString;
+    filename: z.ZodString;
+    options: z.ZodOptional<z.ZodObject<{
+        templateId: z.ZodOptional<z.ZodString>;
+        ocr: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            force: "force";
+            off: "off";
+        }>>;
+        ocrLanguage: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        kind: z.ZodOptional<z.ZodEnum<{
+            outline: "outline";
+            script: "script";
+            bible: "bible";
+            treatment: "treatment";
+            other: "other";
+        }>>;
+        language: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ImportOverJobInput = z.infer<typeof importOverJobInputSchema>;
+/** One document an import made; the job's outputs carry one `conversion-report.json` per document (`output.documentId`). */
+export interface ImportedDocumentRef {
+    documentId: string;
+    title: string;
+    format: string;
+}
+/** What a finished `import.*` job stores as `result` (also readable from the outputs). */
+export interface ImportJobResult {
+    documents: ImportedDocumentRef[];
+    report: ConversionReport;
+}
+/** What a finished `doc.importOver` job stores as `result`. */
+export interface ImportOverJobResult {
+    documentId: string;
+    epoch: number;
+    preImportSnapshotId: string;
+    format: string;
+    report: ConversionReport;
+}
+/** Name of the per-document (import) or per-file (export) conversion report output. */
+export declare const CONVERSION_REPORT_OUTPUT = "conversion-report.json";
+/** Visible watermark. `text` tokens: `{recipient}`, `{email}`, `{company}`, `{title}`, `{date}`. */
+export declare const watermarkStyleSchema: z.ZodObject<{
+    text: z.ZodDefault<z.ZodString>;
+    opacity: z.ZodOptional<z.ZodNumber>;
+    position: z.ZodOptional<z.ZodEnum<{
+        diagonalAscending: "diagonalAscending";
+        diagonalDescending: "diagonalDescending";
+        horizontal: "horizontal";
+    }>>;
+}, z.core.$strip>;
+export type WatermarkStyle = z.input<typeof watermarkStyleSchema>;
+export declare const batchWatermarkSchema: z.ZodObject<{
+    recipients: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        company: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    visible: z.ZodOptional<z.ZodObject<{
+        text: z.ZodDefault<z.ZodString>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodEnum<{
+            diagonalAscending: "diagonalAscending";
+            diagonalDescending: "diagonalDescending";
+            horizontal: "horizontal";
+        }>>;
+    }, z.core.$strip>>;
+    invisible: z.ZodDefault<z.ZodBoolean>;
+    deliver: z.ZodDefault<z.ZodEnum<{
+        email: "email";
+        download: "download";
+    }>>;
+    emailMessage: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type BatchWatermark = z.input<typeof batchWatermarkSchema>;
+export declare const exportOptionsSchema: z.ZodObject<{
+    filename: z.ZodOptional<z.ZodString>;
+    batchWatermark: z.ZodOptional<z.ZodObject<{
+        recipients: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            email: z.ZodOptional<z.ZodString>;
+            company: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        visible: z.ZodOptional<z.ZodObject<{
+            text: z.ZodDefault<z.ZodString>;
+            opacity: z.ZodOptional<z.ZodNumber>;
+            position: z.ZodOptional<z.ZodEnum<{
+                diagonalAscending: "diagonalAscending";
+                diagonalDescending: "diagonalDescending";
+                horizontal: "horizontal";
+            }>>;
+        }, z.core.$strip>>;
+        invisible: z.ZodDefault<z.ZodBoolean>;
+        deliver: z.ZodDefault<z.ZodEnum<{
+            email: "email";
+            download: "download";
+        }>>;
+        emailMessage: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExportOptions = z.input<typeof exportOptionsSchema>;
+/** `POST /documents/:did/exports`. `format` is validated by the server (`EXPORT_FORMAT_UNSUPPORTED` for anything but fountain, fdx, json). */
+export declare const exportCreateSchema: z.ZodObject<{
+    format: z.ZodString;
+    source: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"live">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"snapshot">;
+        snapshotId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"version">;
+        versionId: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+    options: z.ZodOptional<z.ZodObject<{
+        filename: z.ZodOptional<z.ZodString>;
+        batchWatermark: z.ZodOptional<z.ZodObject<{
+            recipients: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                email: z.ZodOptional<z.ZodString>;
+                company: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            visible: z.ZodOptional<z.ZodObject<{
+                text: z.ZodDefault<z.ZodString>;
+                opacity: z.ZodOptional<z.ZodNumber>;
+                position: z.ZodOptional<z.ZodEnum<{
+                    diagonalAscending: "diagonalAscending";
+                    diagonalDescending: "diagonalDescending";
+                    horizontal: "horizontal";
+                }>>;
+            }, z.core.$strip>>;
+            invisible: z.ZodDefault<z.ZodBoolean>;
+            deliver: z.ZodDefault<z.ZodEnum<{
+                email: "email";
+                download: "download";
+            }>>;
+            emailMessage: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExportCreateRequest = z.input<typeof exportCreateSchema>;
+/** `POST /documents/export-combined`: the first document's title page and template, bodies concatenated in the order given. */
+export declare const exportCombinedSchema: z.ZodObject<{
+    documentIds: z.ZodArray<z.ZodString>;
+    format: z.ZodString;
+    options: z.ZodOptional<z.ZodObject<{
+        filename: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExportCombinedRequest = z.input<typeof exportCombinedSchema>;
+/** Input stored on `export.<format>` and `watermark.batch` jobs. */
+export declare const exportJobInputSchema: z.ZodObject<{
+    format: z.ZodEnum<{
+        json: "json";
+        fountain: "fountain";
+        fdx: "fdx";
+    }>;
+    documentIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    source: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"live">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"snapshot">;
+        snapshotId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"version">;
+        versionId: z.ZodString;
+    }, z.core.$strip>], "kind">>;
+    options: z.ZodOptional<z.ZodObject<{
+        filename: z.ZodOptional<z.ZodString>;
+        batchWatermark: z.ZodOptional<z.ZodObject<{
+            recipients: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                email: z.ZodOptional<z.ZodString>;
+                company: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            visible: z.ZodOptional<z.ZodObject<{
+                text: z.ZodDefault<z.ZodString>;
+                opacity: z.ZodOptional<z.ZodNumber>;
+                position: z.ZodOptional<z.ZodEnum<{
+                    diagonalAscending: "diagonalAscending";
+                    diagonalDescending: "diagonalDescending";
+                    horizontal: "horizontal";
+                }>>;
+            }, z.core.$strip>>;
+            invisible: z.ZodDefault<z.ZodBoolean>;
+            deliver: z.ZodDefault<z.ZodEnum<{
+                email: "email";
+                download: "download";
+            }>>;
+            emailMessage: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExportJobInput = z.infer<typeof exportJobInputSchema>;
+/** What a finished `watermark.batch` job stores as `result`. `invisibleApplied` is false for every text format. */
+export interface WatermarkBatchResult {
+    recipients: number;
+    format: JobExportFormat;
+    visibleApplied: boolean;
+    invisibleApplied: boolean;
+    /** How the export code travels in the file. */
+    codeCarrier: 'fountain-note' | 'fdx-comment' | 'json-field';
+}
+/** Prefix of an export code as printed in a file: `FWX-` + 26 base32 characters (128 random bits). */
+export declare const EXPORT_CODE_PREFIX = "FWX-";
+/** `{exportId}` or `{pdfUploadKey}` (a leaked file uploaded through `/uploads/state` with `purpose: "watermark_lookup"`). */
+export declare const watermarkLookupSchema: z.ZodObject<{
+    exportId: z.ZodOptional<z.ZodString>;
+    pdfUploadKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WatermarkLookupRequest = z.input<typeof watermarkLookupSchema>;
+export interface WatermarkMatch {
+    exportId: string;
+    recipient: {
+        name: string;
+        email: string | null;
+        company: string | null;
+    };
+    documentId: string | null;
+    documentTitle: string | null;
+    /** Display name (else email) of who ran the export. */
+    exportedBy: string | null;
+    exportedAt: string;
+    source: {
+        documentId: string | null;
+        kind: 'live' | 'snapshot' | 'version';
+        snapshotId?: string;
+        versionId?: string;
+    };
+}
+export interface WatermarkLookupResponse {
+    matches: WatermarkMatch[];
+}

package/dist/io/index.js

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+import { documentKindSchema } from '../projects/index.js';
+import { docSourceSchema } from '../reads/index.js';
+/**
+ * Imports, exports and batch watermark as jobs, plus the upload port they share (slice B16; spec 05 §6.18, §6.1 `uploads`,
+ * §13). The synchronous `POST /projects/:pid/documents/import`, `POST /documents/:did/export` and `GET /formats` (see
+ * `formats/`) stay until the app migrates.
+ *
+ * Formats are exactly what `writing_formats` has today: import Fountain, FDX and Fade In; export Fountain, FDX and the plain
+ * JSON backup. PDF, DOCX, Celtx, Scrivener and OCR answer `IMPORT_FORMAT_UNSUPPORTED` / `EXPORT_FORMAT_UNSUPPORTED` /
+ * `OCR_UNAVAILABLE`; nothing fakes them.
+ */
+/** Formats `POST /imports` accepts (a job kind `import.<format>` exists for each). */
+export const JOB_IMPORT_FORMATS = ['fountain', 'fdx', 'fadein'];
+/** Formats an export job produces (`export.<format>`). */
+export const JOB_EXPORT_FORMATS = ['fountain', 'fdx', 'json'];
+/** `POST /documents/export-combined` takes these (spec 05: pdf, fdx, fountain; pdf is not built). */
+export const COMBINED_EXPORT_FORMATS = ['fdx', 'fountain'];
+/** At most this many documents in one combined export (the job's `sources` cap). */
+export const COMBINED_EXPORT_MAX_DOCUMENTS = 20;
+/** At most this many recipients in one batch watermark (spec 05 §6.18). */
+export const BATCH_WATERMARK_MAX_RECIPIENTS = 500;
+// ─── uploads (spec 05 §6.1 `uploads`, §8) ─────────────────────────────────────
+export const UPLOAD_PURPOSES = ['state', 'watermark_lookup', 'import'];
+const sha256HexSchema = z
+    .string()
+    .regex(/^[0-9a-fA-F]{64}$/, 'sha256Hex must be 64 hex characters');
+/**
+ * `POST /uploads/state`. `purpose` defaults to `state` (a Yjs state blob); `watermark_lookup` is a leaked file for
+ * `POST /workspaces/:wid/watermark-lookup`. `import` uploads are created by `POST /imports`, never here.
+ */
+export const uploadStateRequestSchema = z.object({
+    sizeBytes: z.number().int().min(1),
+    sha256Hex: sha256HexSchema,
+    purpose: z.enum(['state', 'watermark_lookup']).default('state'),
+});
+// ─── imports ─────────────────────────────────────────────────────────────────
+export const importOptionsSchema = z.object({
+    templateId: z.string().min(1).optional(),
+    /** `auto`: OCR a PDF without a text layer; `force`; `off`. No OCR exists yet: `force` is `OCR_UNAVAILABLE`. */
+    ocr: z.enum(['auto', 'force', 'off']).default('auto'),
+    ocrLanguage: z.string().min(2).max(16).optional(),
+    title: z.string().trim().min(1).max(200).optional(),
+    kind: documentKindSchema.optional(),
+    language: z.string().max(16).optional(),
+});
+const importFileFields = {
+    filename: z.string().min(1).max(500),
+    sizeBytes: z.number().int().min(1),
+    sha256Hex: sha256HexSchema,
+    /** Auto-detected from the uploaded bytes when omitted. */
+    format: z.string().min(1).max(32).optional(),
+    options: importOptionsSchema.optional(),
+};
+/** `POST /imports`: one of `targetProjectId` (import as a new document) or `templateTarget` (a template file, `POST /templates/import {importId}`). */
+export const importCreateSchema = z
+    .object({
+    targetProjectId: z.string().min(1).optional(),
+    templateTarget: z
+        .object({
+        scope: z.enum(['user', 'workspace']),
+        workspaceId: z.string().min(1).optional(),
+    })
+        .refine((v) => v.scope !== 'workspace' || !!v.workspaceId, {
+        message: 'workspaceId is required for a workspace template',
+        path: ['workspaceId'],
+    })
+        .optional(),
+    ...importFileFields,
+})
+    .refine((v) => (v.targetProjectId ? 1 : 0) + (v.templateTarget ? 1 : 0) === 1, {
+    message: 'Send exactly one of targetProjectId and templateTarget',
+    path: ['targetProjectId'],
+});
+/** `POST /documents/:did/import-over`: the document is the route's. */
+export const importOverSchema = z.object(importFileFields);
+/** Input stored on `import.<format>` jobs (spec 05 §13). `newDocumentId` is minted at start so a retried run cannot make two documents. */
+export const importJobInputSchema = z.object({
+    importId: z.string().min(1),
+    targetProjectId: z.string().min(1),
+    newDocumentId: z.string().min(1),
+    filename: z.string().min(1).max(500),
+    options: importOptionsSchema.optional(),
+});
+/** Input stored on `doc.importOver` jobs. */
+export const importOverJobInputSchema = z.object({
+    importId: z.string().min(1),
+    documentId: z.string().min(1),
+    filename: z.string().min(1).max(500),
+    options: importOptionsSchema.optional(),
+});
+/** Name of the per-document (import) or per-file (export) conversion report output. */
+export const CONVERSION_REPORT_OUTPUT = 'conversion-report.json';
+// ─── exports ─────────────────────────────────────────────────────────────────
+/** Visible watermark. `text` tokens: `{recipient}`, `{email}`, `{company}`, `{title}`, `{date}`. */
+export const watermarkStyleSchema = z.object({
+    text: z.string().min(1).max(200).default('{recipient}'),
+    opacity: z.number().min(0.05).max(1).optional(),
+    position: z
+        .enum(['diagonalAscending', 'diagonalDescending', 'horizontal'])
+        .optional(),
+});
+export const batchWatermarkSchema = z.object({
+    recipients: z
+        .array(z.object({
+        name: z.string().trim().min(1).max(200),
+        email: z.string().trim().min(1).max(320).optional(),
+        company: z.string().trim().min(1).max(200).optional(),
+    }))
+        .min(1)
+        .max(BATCH_WATERMARK_MAX_RECIPIENTS),
+    visible: watermarkStyleSchema.optional(),
+    /** Forensic mark. Only a PDF writer can embed one; text formats carry the export code as a visible note (see the API notes). */
+    invisible: z.boolean().default(false),
+    /** `email` needs the notification slice (B12): refused with `VALIDATION` until then. */
+    deliver: z.enum(['download', 'email']).default('download'),
+    emailMessage: z.string().max(2000).optional(),
+});
+export const exportOptionsSchema = z.object({
+    /** Download name without extension (default: the document title). */
+    filename: z.string().trim().min(1).max(120).optional(),
+    batchWatermark: batchWatermarkSchema.optional(),
+});
+/** `POST /documents/:did/exports`. `format` is validated by the server (`EXPORT_FORMAT_UNSUPPORTED` for anything but fountain, fdx, json). */
+export const exportCreateSchema = z.object({
+    format: z.string().min(1).max(32),
+    source: docSourceSchema.optional(),
+    options: exportOptionsSchema.optional(),
+});
+/** `POST /documents/export-combined`: the first document's title page and template, bodies concatenated in the order given. */
+export const exportCombinedSchema = z.object({
+    documentIds: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(COMBINED_EXPORT_MAX_DOCUMENTS),
+    format: z.string().min(1).max(32),
+    options: exportOptionsSchema.omit({ batchWatermark: true }).optional(),
+});
+/** Input stored on `export.<format>` and `watermark.batch` jobs. */
+export const exportJobInputSchema = z.object({
+    format: z.enum(JOB_EXPORT_FORMATS),
+    documentIds: z
+        .array(z.string().min(1))
+        .max(COMBINED_EXPORT_MAX_DOCUMENTS)
+        .optional(),
+    source: docSourceSchema.optional(),
+    options: exportOptionsSchema.optional(),
+});
+// ─── watermark lookup ────────────────────────────────────────────────────────
+/** Prefix of an export code as printed in a file: `FWX-` + 26 base32 characters (128 random bits). */
+export const EXPORT_CODE_PREFIX = 'FWX-';
+/** `{exportId}` or `{pdfUploadKey}` (a leaked file uploaded through `/uploads/state` with `purpose: "watermark_lookup"`). */
+export const watermarkLookupSchema = z
+    .object({
+    exportId: z.string().trim().min(8).max(64).optional(),
+    pdfUploadKey: z.string().min(1).max(100).optional(),
+})
+    .refine((v) => (v.exportId ? 1 : 0) + (v.pdfUploadKey ? 1 : 0) === 1, {
+    message: 'Send exactly one of exportId and pdfUploadKey',
+    path: ['exportId'],
+});