react-next-editor-js 0.1.0

package/dist/server/index.d.cts

@@ -0,0 +1,229 @@
+import { D as DocumentJSON, P as PageConfig } from '../types-B4z0Quvv.cjs';
+import { T as TextConversionOptions, b as DocxNodeConverter } from '../docx-DLfSdvXm.cjs';
+import 'docx';
+
+/**
+ * Programmatic export service types (§5.6.2, §8.8). This module is server-side
+ * (Node) and never imports the React layer or any DOM. It consumes the same
+ * isomorphic converters the client uses, so output is consistent (F-6.11).
+ *
+ * It is OPTIONAL and additive (C-1): editing and offline/client export do not
+ * depend on it.
+ */
+/** Supported programmatic export formats. */
+type ServerExportFormat = 'docx' | 'pdf' | 'txt' | 'html';
+/** MIME types for the supported formats. */
+declare const CONTENT_TYPES: Record<ServerExportFormat, string>;
+declare const FILE_EXTENSIONS: Record<ServerExportFormat, string>;
+/** A single export request: a document (by id or inline) and a target format. */
+interface ExportRequest {
+    /** Stored document id, resolved via the injected {@link DocumentStoreReader}. */
+    documentId?: string;
+    /** Inline document JSON (used instead of, or as a fallback for, `documentId`). */
+    documentJson?: DocumentJSON;
+    format: ServerExportFormat;
+    options?: {
+        page?: PageConfig;
+        title?: string;
+        /** Base filename (without extension). Defaults to documentId/title/'document'. */
+        filename?: string;
+        text?: TextConversionOptions;
+    };
+    /**
+     * When true (and a {@link StorageAdapter} is configured), the rendered file is
+     * written to storage and a reference/URL is returned (F-6.10). Otherwise the
+     * bytes are returned inline.
+     */
+    store?: boolean;
+}
+/** Result of a single export. Never throws; failures are reported here (F-6.17). */
+interface ExportResult {
+    status: 'ok' | 'error';
+    format: ServerExportFormat;
+    filename: string;
+    contentType: string;
+    /** Present when not stored: the rendered bytes. */
+    bytes?: Uint8Array;
+    /** Present when stored: a URL to fetch the file. */
+    url?: string;
+    /** Present when stored: an opaque storage reference (e.g. a path or key). */
+    ref?: string;
+    /** Identifies which input produced this result in a batch. */
+    documentId?: string;
+    error?: string;
+}
+/**
+ * Reads stored document JSON by id, without a live editor (F-6.9). Inject your
+ * backend/data-store implementation.
+ */
+interface DocumentStoreReader {
+    loadDocument(id: string): Promise<DocumentJSON | null>;
+}
+/**
+ * Persists rendered files to system/object storage and returns a reference/URL
+ * (F-6.10). Filesystem and in-memory implementations ship with the package.
+ */
+interface StorageAdapter {
+    write(key: string, data: Uint8Array, contentType: string): Promise<{
+        url: string;
+        ref: string;
+    }>;
+}
+/**
+ * Renders the shared print HTML to a PDF using a headless browser (F-6.14).
+ * Injected so the package does not hard-depend on Puppeteer/Playwright. A
+ * Playwright-based factory is provided ({@link createPlaywrightPdfRenderer}).
+ */
+interface PdfRenderer {
+    render(html: string, options?: {
+        page?: PageConfig;
+    }): Promise<Uint8Array>;
+    /** Release resources (e.g. close the browser). */
+    close?(): Promise<void>;
+}
+/** Context passed to the authorization hook (e.g. headers, token, user). */
+interface ExportAuthContext {
+    headers?: Record<string, string | undefined>;
+    token?: string | null;
+    [key: string]: unknown;
+}
+interface ExportServiceOptions {
+    /** Resolves `documentId` to stored JSON (F-6.9). Required for id-based exports. */
+    store?: DocumentStoreReader;
+    /** Writes rendered files to storage (F-6.10). Required for `store: true` exports. */
+    storage?: StorageAdapter;
+    /** Server PDF renderer (F-6.14). Required for `format: 'pdf'`. */
+    pdfRenderer?: PdfRenderer;
+    /** Custom DOCX node converters, matching the client's (F-6.16). */
+    nodeConverters?: Record<string, DocxNodeConverter>;
+    /**
+     * Authorize a request and its document access (F-6.15). Return false to reject.
+     * Throwing is also treated as a rejection.
+     */
+    authorize?: (request: ExportRequest, context: ExportAuthContext) => Promise<boolean> | boolean;
+}
+/** Status of an asynchronous batch job (F-6.13). */
+interface ExportJob {
+    id: string;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    total: number;
+    completed: number;
+    results: ExportResult[];
+    createdAt: number;
+    finishedAt?: number;
+    error?: string;
+}
+
+/**
+ * The programmatic export service (§8.8). Converts our own stored/inline JSON to
+ * DOCX/PDF/text/HTML using the shared isomorphic converters, optionally persists
+ * the result to storage, and reports per-document status. It is authenticated/
+ * access-controlled via the injected `authorize` hook (F-6.15) and never emits a
+ * malformed file silently — failures are returned as `status: 'error'` (F-6.17).
+ */
+declare class ExportService {
+    private readonly options;
+    private readonly jobs;
+    private jobSeq;
+    constructor(options?: ExportServiceOptions);
+    /** Render a single export request (synchronous result). */
+    export(request: ExportRequest, context?: ExportAuthContext): Promise<ExportResult>;
+    /**
+     * Render multiple requests in one call (F-6.12), each with independent status
+     * (F-6.17). Failures of one item do not abort the others.
+     */
+    exportBatch(requests: ExportRequest[], context?: ExportAuthContext): Promise<ExportResult[]>;
+    /**
+     * Enqueue a batch as an asynchronous job (F-6.13). Returns immediately with a
+     * job id; poll {@link getJob} for status/results. This is a simple in-process
+     * runner — swap in a durable queue (e.g. BullMQ) for production scale.
+     */
+    enqueue(requests: ExportRequest[], context?: ExportAuthContext): {
+        jobId: string;
+    };
+    /** Look up an async job's status and results. */
+    getJob(jobId: string): ExportJob | null;
+    /** Release renderer resources (e.g. close the headless browser). */
+    close(): Promise<void>;
+    private baseResult;
+    private resolveDocument;
+    private render;
+}
+/** Create a configured {@link ExportService}. */
+declare function createExportService(options?: ExportServiceOptions): ExportService;
+
+/**
+ * A web-standard `(Request) => Promise<Response>` handler factory for the export
+ * service (F-6.8). It works directly as a Next.js App Router route handler, or
+ * in any Fetch-API server. Authentication is delegated to the service's
+ * `authorize` hook; the Bearer token (if any) is passed through as context.
+ *
+ * Request body shapes (POST, JSON):
+ *   - `{ jobId }`                        → returns the async job status
+ *   - `{ async: true, requests: [...] }` → enqueues a batch, returns `{ jobId }`
+ *   - `{ requests: [...] }`              → synchronous batch, returns `{ results }`
+ *   - a single {@link ExportRequest}     → returns the file (binary) or a `{ url }`
+ */
+declare function createExportHandler(service: ExportService): (request: Request) => Promise<Response>;
+
+/**
+ * In-memory {@link StorageAdapter} — useful for tests and serverless contexts
+ * that hand bytes off elsewhere. URLs are `memory:` references.
+ */
+declare class MemoryStorage implements StorageAdapter {
+    private files;
+    write(key: string, data: Uint8Array, contentType: string): Promise<{
+        url: string;
+        ref: string;
+    }>;
+    get(key: string): {
+        data: Uint8Array;
+        contentType: string;
+    } | undefined;
+    keys(): string[];
+}
+interface FilesystemStorageOptions {
+    /** Directory rendered files are written under. */
+    baseDir: string;
+    /**
+     * Public base URL files are served from. The returned `url` is
+     * `${baseUrl}/${key}`. If omitted, `url` mirrors the on-disk path.
+     */
+    baseUrl?: string;
+}
+/**
+ * Filesystem {@link StorageAdapter} (F-6.10). Writes rendered files under a base
+ * directory and returns a URL/reference. Uses `node:fs` lazily so the module can
+ * be imported anywhere without eagerly pulling Node built-ins.
+ */
+declare class FilesystemStorage implements StorageAdapter {
+    private readonly baseDir;
+    private readonly baseUrl?;
+    constructor(options: FilesystemStorageOptions);
+    write(key: string, data: Uint8Array, _contentType: string): Promise<{
+        url: string;
+        ref: string;
+    }>;
+}
+
+interface PlaywrightPdfOptions {
+    /** Print background colors/images. Default true. */
+    printBackground?: boolean;
+    /** Honour the document's `@page` size rules. Default true. */
+    preferCSSPageSize?: boolean;
+    /** Launch arguments forwarded to chromium. */
+    launchArgs?: string[];
+}
+/**
+ * PDF renderer backed by Playwright's bundled Chromium. Requires `playwright`
+ * to be installed in the host. The browser is launched lazily and reused;
+ * call `close()` to release it.
+ */
+declare function createPlaywrightPdfRenderer(options?: PlaywrightPdfOptions): PdfRenderer;
+/**
+ * PDF renderer backed by Puppeteer. Requires `puppeteer` to be installed.
+ * Equivalent behaviour to the Playwright renderer.
+ */
+declare function createPuppeteerPdfRenderer(options?: PlaywrightPdfOptions): PdfRenderer;
+
+export { CONTENT_TYPES, type DocumentStoreReader, type ExportAuthContext, type ExportJob, type ExportRequest, type ExportResult, ExportService, type ExportServiceOptions, FILE_EXTENSIONS, FilesystemStorage, type FilesystemStorageOptions, MemoryStorage, type PdfRenderer, type PlaywrightPdfOptions, type ServerExportFormat, type StorageAdapter, createExportHandler, createExportService, createPlaywrightPdfRenderer, createPuppeteerPdfRenderer };

package/dist/server/index.d.ts

@@ -0,0 +1,229 @@
+import { D as DocumentJSON, P as PageConfig } from '../types-B4z0Quvv.js';
+import { T as TextConversionOptions, b as DocxNodeConverter } from '../docx-BUrf4PFj.js';
+import 'docx';
+
+/**
+ * Programmatic export service types (§5.6.2, §8.8). This module is server-side
+ * (Node) and never imports the React layer or any DOM. It consumes the same
+ * isomorphic converters the client uses, so output is consistent (F-6.11).
+ *
+ * It is OPTIONAL and additive (C-1): editing and offline/client export do not
+ * depend on it.
+ */
+/** Supported programmatic export formats. */
+type ServerExportFormat = 'docx' | 'pdf' | 'txt' | 'html';
+/** MIME types for the supported formats. */
+declare const CONTENT_TYPES: Record<ServerExportFormat, string>;
+declare const FILE_EXTENSIONS: Record<ServerExportFormat, string>;
+/** A single export request: a document (by id or inline) and a target format. */
+interface ExportRequest {
+    /** Stored document id, resolved via the injected {@link DocumentStoreReader}. */
+    documentId?: string;
+    /** Inline document JSON (used instead of, or as a fallback for, `documentId`). */
+    documentJson?: DocumentJSON;
+    format: ServerExportFormat;
+    options?: {
+        page?: PageConfig;
+        title?: string;
+        /** Base filename (without extension). Defaults to documentId/title/'document'. */
+        filename?: string;
+        text?: TextConversionOptions;
+    };
+    /**
+     * When true (and a {@link StorageAdapter} is configured), the rendered file is
+     * written to storage and a reference/URL is returned (F-6.10). Otherwise the
+     * bytes are returned inline.
+     */
+    store?: boolean;
+}
+/** Result of a single export. Never throws; failures are reported here (F-6.17). */
+interface ExportResult {
+    status: 'ok' | 'error';
+    format: ServerExportFormat;
+    filename: string;
+    contentType: string;
+    /** Present when not stored: the rendered bytes. */
+    bytes?: Uint8Array;
+    /** Present when stored: a URL to fetch the file. */
+    url?: string;
+    /** Present when stored: an opaque storage reference (e.g. a path or key). */
+    ref?: string;
+    /** Identifies which input produced this result in a batch. */
+    documentId?: string;
+    error?: string;
+}
+/**
+ * Reads stored document JSON by id, without a live editor (F-6.9). Inject your
+ * backend/data-store implementation.
+ */
+interface DocumentStoreReader {
+    loadDocument(id: string): Promise<DocumentJSON | null>;
+}
+/**
+ * Persists rendered files to system/object storage and returns a reference/URL
+ * (F-6.10). Filesystem and in-memory implementations ship with the package.
+ */
+interface StorageAdapter {
+    write(key: string, data: Uint8Array, contentType: string): Promise<{
+        url: string;
+        ref: string;
+    }>;
+}
+/**
+ * Renders the shared print HTML to a PDF using a headless browser (F-6.14).
+ * Injected so the package does not hard-depend on Puppeteer/Playwright. A
+ * Playwright-based factory is provided ({@link createPlaywrightPdfRenderer}).
+ */
+interface PdfRenderer {
+    render(html: string, options?: {
+        page?: PageConfig;
+    }): Promise<Uint8Array>;
+    /** Release resources (e.g. close the browser). */
+    close?(): Promise<void>;
+}
+/** Context passed to the authorization hook (e.g. headers, token, user). */
+interface ExportAuthContext {
+    headers?: Record<string, string | undefined>;
+    token?: string | null;
+    [key: string]: unknown;
+}
+interface ExportServiceOptions {
+    /** Resolves `documentId` to stored JSON (F-6.9). Required for id-based exports. */
+    store?: DocumentStoreReader;
+    /** Writes rendered files to storage (F-6.10). Required for `store: true` exports. */
+    storage?: StorageAdapter;
+    /** Server PDF renderer (F-6.14). Required for `format: 'pdf'`. */
+    pdfRenderer?: PdfRenderer;
+    /** Custom DOCX node converters, matching the client's (F-6.16). */
+    nodeConverters?: Record<string, DocxNodeConverter>;
+    /**
+     * Authorize a request and its document access (F-6.15). Return false to reject.
+     * Throwing is also treated as a rejection.
+     */
+    authorize?: (request: ExportRequest, context: ExportAuthContext) => Promise<boolean> | boolean;
+}
+/** Status of an asynchronous batch job (F-6.13). */
+interface ExportJob {
+    id: string;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    total: number;
+    completed: number;
+    results: ExportResult[];
+    createdAt: number;
+    finishedAt?: number;
+    error?: string;
+}
+
+/**
+ * The programmatic export service (§8.8). Converts our own stored/inline JSON to
+ * DOCX/PDF/text/HTML using the shared isomorphic converters, optionally persists
+ * the result to storage, and reports per-document status. It is authenticated/
+ * access-controlled via the injected `authorize` hook (F-6.15) and never emits a
+ * malformed file silently — failures are returned as `status: 'error'` (F-6.17).
+ */
+declare class ExportService {
+    private readonly options;
+    private readonly jobs;
+    private jobSeq;
+    constructor(options?: ExportServiceOptions);
+    /** Render a single export request (synchronous result). */
+    export(request: ExportRequest, context?: ExportAuthContext): Promise<ExportResult>;
+    /**
+     * Render multiple requests in one call (F-6.12), each with independent status
+     * (F-6.17). Failures of one item do not abort the others.
+     */
+    exportBatch(requests: ExportRequest[], context?: ExportAuthContext): Promise<ExportResult[]>;
+    /**
+     * Enqueue a batch as an asynchronous job (F-6.13). Returns immediately with a
+     * job id; poll {@link getJob} for status/results. This is a simple in-process
+     * runner — swap in a durable queue (e.g. BullMQ) for production scale.
+     */
+    enqueue(requests: ExportRequest[], context?: ExportAuthContext): {
+        jobId: string;
+    };
+    /** Look up an async job's status and results. */
+    getJob(jobId: string): ExportJob | null;
+    /** Release renderer resources (e.g. close the headless browser). */
+    close(): Promise<void>;
+    private baseResult;
+    private resolveDocument;
+    private render;
+}
+/** Create a configured {@link ExportService}. */
+declare function createExportService(options?: ExportServiceOptions): ExportService;
+
+/**
+ * A web-standard `(Request) => Promise<Response>` handler factory for the export
+ * service (F-6.8). It works directly as a Next.js App Router route handler, or
+ * in any Fetch-API server. Authentication is delegated to the service's
+ * `authorize` hook; the Bearer token (if any) is passed through as context.
+ *
+ * Request body shapes (POST, JSON):
+ *   - `{ jobId }`                        → returns the async job status
+ *   - `{ async: true, requests: [...] }` → enqueues a batch, returns `{ jobId }`
+ *   - `{ requests: [...] }`              → synchronous batch, returns `{ results }`
+ *   - a single {@link ExportRequest}     → returns the file (binary) or a `{ url }`
+ */
+declare function createExportHandler(service: ExportService): (request: Request) => Promise<Response>;
+
+/**
+ * In-memory {@link StorageAdapter} — useful for tests and serverless contexts
+ * that hand bytes off elsewhere. URLs are `memory:` references.
+ */
+declare class MemoryStorage implements StorageAdapter {
+    private files;
+    write(key: string, data: Uint8Array, contentType: string): Promise<{
+        url: string;
+        ref: string;
+    }>;
+    get(key: string): {
+        data: Uint8Array;
+        contentType: string;
+    } | undefined;
+    keys(): string[];
+}
+interface FilesystemStorageOptions {
+    /** Directory rendered files are written under. */
+    baseDir: string;
+    /**
+     * Public base URL files are served from. The returned `url` is
+     * `${baseUrl}/${key}`. If omitted, `url` mirrors the on-disk path.
+     */
+    baseUrl?: string;
+}
+/**
+ * Filesystem {@link StorageAdapter} (F-6.10). Writes rendered files under a base
+ * directory and returns a URL/reference. Uses `node:fs` lazily so the module can
+ * be imported anywhere without eagerly pulling Node built-ins.
+ */
+declare class FilesystemStorage implements StorageAdapter {
+    private readonly baseDir;
+    private readonly baseUrl?;
+    constructor(options: FilesystemStorageOptions);
+    write(key: string, data: Uint8Array, _contentType: string): Promise<{
+        url: string;
+        ref: string;
+    }>;
+}
+
+interface PlaywrightPdfOptions {
+    /** Print background colors/images. Default true. */
+    printBackground?: boolean;
+    /** Honour the document's `@page` size rules. Default true. */
+    preferCSSPageSize?: boolean;
+    /** Launch arguments forwarded to chromium. */
+    launchArgs?: string[];
+}
+/**
+ * PDF renderer backed by Playwright's bundled Chromium. Requires `playwright`
+ * to be installed in the host. The browser is launched lazily and reused;
+ * call `close()` to release it.
+ */
+declare function createPlaywrightPdfRenderer(options?: PlaywrightPdfOptions): PdfRenderer;
+/**
+ * PDF renderer backed by Puppeteer. Requires `puppeteer` to be installed.
+ * Equivalent behaviour to the Playwright renderer.
+ */
+declare function createPuppeteerPdfRenderer(options?: PlaywrightPdfOptions): PdfRenderer;
+
+export { CONTENT_TYPES, type DocumentStoreReader, type ExportAuthContext, type ExportJob, type ExportRequest, type ExportResult, ExportService, type ExportServiceOptions, FILE_EXTENSIONS, FilesystemStorage, type FilesystemStorageOptions, MemoryStorage, type PdfRenderer, type PlaywrightPdfOptions, type ServerExportFormat, type StorageAdapter, createExportHandler, createExportService, createPlaywrightPdfRenderer, createPuppeteerPdfRenderer };