@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/types/modules/word/docx-packager.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DOCX Module - Packager
+ *
+ * Assembles a DocxDocument model into a DOCX ZIP package using the
+ * archive and XML modules. Supports all parts including comments,
+ * custom properties, document background, hyperlink relationships,
+ * and per-header/footer relationship files.
+ */
+import type { DocxDocument } from "./types.js";
+/**
+ * Package a DocxDocument model into a DOCX ZIP file.
+ * Returns the ZIP bytes as Uint8Array.
+ */
+export declare function packageDocx(doc: DocxDocument, compressionLevel?: number): Promise<Uint8Array>;

package/dist/types/modules/word/docx-reader.d.ts

@@ -0,0 +1,11 @@
+/**
+ * DOCX Module - Reader / Parser
+ *
+ * Reads a DOCX ZIP file and parses it into a DocxDocument model.
+ * Uses the archive module for ZIP reading and XML module for parsing.
+ */
+import type { DocxDocument } from "./types.js";
+/**
+ * Read a DOCX file from a Uint8Array buffer and parse it into a DocxDocument model.
+ */
+export declare function readDocx(buffer: Uint8Array): Promise<DocxDocument>;

package/dist/types/modules/word/encryption.d.ts

@@ -0,0 +1,102 @@
+/**
+ * DOCX Agile Encryption (MS-OFFCRYPTO)
+ *
+ * Implements ECMA-376 Agile Encryption (used by Office 2010+) for encrypted
+ * DOCX files. Encrypted DOCX files use the CFB (Compound File Binary) format
+ * to wrap the ZIP content.
+ *
+ * This module provides:
+ * - Password-based encryption/decryption of DOCX content
+ * - EncryptionInfo XML generation/parsing
+ *
+ * Note: A full implementation requires a CFB container reader/writer for the
+ * outer compound document format. For now, we expose primitives that can be
+ * combined with an external CFB library if needed.
+ *
+ * References:
+ *   - MS-OFFCRYPTO: Office Document Cryptography Structure
+ *   - ECMA-376 Part 3: Markup Compatibility and Extensibility
+ */
+/** Agile encryption parameters. */
+export interface AgileEncryptionInfo {
+    /** Cipher algorithm (AES). */
+    readonly cipherAlgorithm: "AES";
+    /** Cipher chaining mode. */
+    readonly cipherChaining: "ChainingModeCBC";
+    /** Key bit length (128, 192, 256). */
+    readonly keyBits: 128 | 192 | 256;
+    /** Hash algorithm. */
+    readonly hashAlgorithm: "SHA1" | "SHA256" | "SHA384" | "SHA512";
+    /** Hash output size in bytes. */
+    readonly hashSize: number;
+    /** Number of iterations (spin count). */
+    readonly spinCount: number;
+    /** Salt for key derivation (16 bytes). */
+    readonly keySalt: Uint8Array;
+    /** Encrypted verifier hash input. */
+    readonly encryptedVerifierHashInput: Uint8Array;
+    /** Encrypted verifier hash value. */
+    readonly encryptedVerifierHashValue: Uint8Array;
+    /** Encrypted key value. */
+    readonly encryptedKeyValue: Uint8Array;
+    /** Block size (16 for AES). */
+    readonly blockSize: number;
+    /** Data integrity salt. */
+    readonly dataIntegritySalt?: Uint8Array;
+    /** Data integrity HMAC value. */
+    readonly dataIntegrityHmac?: Uint8Array;
+}
+/** Detect whether a buffer is an encrypted Office document (CFB format). */
+export declare function isEncryptedDocx(buffer: Uint8Array): boolean;
+/**
+ * Derive an encryption key from a password using the agile encryption KDF.
+ *
+ * Per MS-OFFCRYPTO 2.3.4.11:
+ *   H_0 = H(salt + password)
+ *   H_i = H(iterator + H_{i-1})  for i = 0..spinCount-1
+ *   H_final = H(H_{spinCount} + blockKey)
+ *   Key = first keySize bytes of H_final
+ */
+export declare function deriveEncryptionKey(password: string, info: {
+    keySalt: Uint8Array;
+    spinCount: number;
+    hashAlgorithm: string;
+    keyBits: number;
+}, blockKey: Uint8Array): Promise<Uint8Array>;
+/** Block keys as defined in MS-OFFCRYPTO 2.3.4.13. */
+export declare const AGILE_BLOCK_KEYS: {
+    /** For encrypting verifier hash input. */
+    readonly verifierHashInput: Uint8Array<ArrayBuffer>;
+    /** For encrypting verifier hash value. */
+    readonly verifierHashValue: Uint8Array<ArrayBuffer>;
+    /** For encrypting the main key. */
+    readonly encryptedKey: Uint8Array<ArrayBuffer>;
+    /** For data integrity HMAC key. */
+    readonly dataIntegrityKey: Uint8Array<ArrayBuffer>;
+    /** For data integrity HMAC value. */
+    readonly dataIntegrityValue: Uint8Array<ArrayBuffer>;
+};
+/**
+ * Verify a password against the encryption info.
+ *
+ * @returns True if password is correct.
+ */
+export declare function verifyPassword(password: string, info: AgileEncryptionInfo): Promise<boolean>;
+/**
+ * Decrypt the package data using the password.
+ *
+ * @param encryptedPackage - The EncryptedPackage stream from CFB.
+ * @param info - Agile encryption parameters.
+ * @param password - The user password.
+ * @returns The decrypted (unencrypted) package bytes.
+ */
+export declare function decryptPackage(encryptedPackage: Uint8Array, info: AgileEncryptionInfo, password: string): Promise<Uint8Array>;
+/**
+ * Parse an EncryptionInfo XML stream from a CFB-wrapped encrypted DOCX.
+ *
+ * This is the UTF-8 XML part after the 8-byte version/flags header.
+ *
+ * @param xmlStr - The EncryptionInfo XML content.
+ * @returns Parsed agile encryption info.
+ */
+export declare function parseEncryptionInfoXml(xmlStr: string): AgileEncryptionInfo;

package/dist/types/modules/word/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * DOCX module error types.
+ *
+ * All DOCX-related errors extend DocxError.
+ */
+import { BaseError, type BaseErrorOptions } from "../../utils/errors.js";
+export { AbortError, createAbortError, isAbortError, throwIfAborted, createLinkedAbortController, toError, suppressUnhandledRejection, errorToJSON, getErrorChain, getRootCause, type BaseErrorOptions } from "../../utils/errors.js";
+/**
+ * Base class for all DOCX-related errors.
+ */
+export declare class DocxError extends BaseError {
+    constructor(message: string, options?: BaseErrorOptions);
+}
+/**
+ * Check if an error is a DOCX error.
+ */
+export declare function isDocxError(err: unknown): err is DocxError;
+/**
+ * Error thrown when DOCX parsing fails.
+ */
+export declare class DocxParseError extends DocxError {
+    name: string;
+}
+/**
+ * Error thrown when DOCX generation/writing fails.
+ */
+export declare class DocxWriteError extends DocxError {
+    name: string;
+}
+/**
+ * Error thrown when a required DOCX part is missing.
+ */
+export declare class DocxMissingPartError extends DocxParseError {
+    name: string;
+    constructor(partPath: string);
+}
+/**
+ * Error thrown when document structure is invalid.
+ */
+export declare class DocxInvalidStructureError extends DocxParseError {
+    name: string;
+}
+/**
+ * Error thrown when an unsupported feature is encountered during parsing.
+ */
+export declare class DocxUnsupportedFeatureError extends DocxError {
+    name: string;
+    constructor(feature: string);
+}

package/dist/types/modules/word/font-obfuscation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * DOCX Font Obfuscation (ODTTF format)
+ *
+ * Per ECMA-376 Part 3, Section 4, embedded TrueType fonts may be obfuscated by
+ * XOR-ing the first 32 bytes of the font file with a 16-byte GUID repeated twice.
+ *
+ * The GUID in the w:fontKey attribute is in the form "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"
+ * but bytes are applied in a specific order derived from the GUID.
+ */
+/**
+ * Deobfuscate ODTTF font data to raw TTF/OTF.
+ *
+ * @param data - The obfuscated font data (first 32 bytes are obfuscated).
+ * @param fontKey - The GUID from w:fontKey attribute.
+ * @returns The deobfuscated font data (new buffer).
+ */
+export declare function deobfuscateFont(data: Uint8Array, fontKey: string): Uint8Array;
+/**
+ * Obfuscate a raw TTF/OTF font to ODTTF format.
+ *
+ * @param data - The raw font data.
+ * @param fontKey - The GUID to use for obfuscation (also stored in w:fontKey).
+ * @returns The obfuscated font data (new buffer).
+ */
+export declare function obfuscateFont(data: Uint8Array, fontKey: string): Uint8Array;
+/**
+ * Generate a new random GUID suitable for w:fontKey.
+ *
+ * @returns A GUID string in the form "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"
+ */
+export declare function generateFontKey(): string;

package/dist/types/modules/word/html-renderer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * DOCX Module - HTML Renderer
+ *
+ * Converts a DocxDocument model to semantic HTML5.
+ * Supports paragraphs, runs with formatting, tables, lists, images, hyperlinks,
+ * headings, comments, footnotes/endnotes, and more.
+ */
+import type { DocxDocument } from "./types.js";
+/** Options for HTML rendering. */
+export interface HtmlRenderOptions {
+    /** Include CSS inline in a <style> tag. Default: true. */
+    readonly includeStyles?: boolean;
+    /** Wrap output in complete HTML document. Default: true. */
+    readonly fullDocument?: boolean;
+    /** Page title for full document. Default: core property "title" or "Document". */
+    readonly title?: string;
+    /** Base URL for image data: URLs vs file references. "dataUrl" embeds images as base64. */
+    readonly imageMode?: "dataUrl" | "filename" | "none";
+    /** Convert comments to HTML. Default: false. */
+    readonly includeComments?: boolean;
+    /** Render footnotes/endnotes as anchored references. Default: true. */
+    readonly includeNotes?: boolean;
+    /** Custom CSS class prefix (default: "docx-"). */
+    readonly classPrefix?: string;
+}
+/** The result of HTML rendering. */
+export interface HtmlRenderResult {
+    /** Generated HTML string. */
+    readonly html: string;
+    /** Warnings encountered during rendering. */
+    readonly warnings: readonly string[];
+    /** Image map: file name → data URL or reference. */
+    readonly images: ReadonlyMap<string, string>;
+}
+/**
+ * Convert a DocxDocument to HTML.
+ */
+export declare function renderToHtml(doc: DocxDocument, options?: HtmlRenderOptions): HtmlRenderResult;

package/dist/types/modules/word/index.base.d.ts

@@ -0,0 +1,19 @@
+/**
+ * DOCX Module - Base Exports (Platform Independent)
+ *
+ * Shared exports for both Node.js and browser environments.
+ */
+export type { HalfPoint, Twips, Emu, EighthPoint, HexColor, ShadingType, BorderStyle, PageOrientation, PageSize, PageMargins, ColumnDef, SectionColumns, SectionBreakType, PageNumberFormat, HeaderFooterType, HeaderFooterRef, PageVerticalAlign, DocumentGridType, PageTextDirection, Border, ArtBorderType, PageBorders, SectionProperties, UnderlineStyle, VerticalAlign, HighlightColor, FontSpec, Shading, UnderlineSpec, TextEffect, EmphasisMarkType, ColorSpec, RunProperties, RunContent, TextContent, BreakContent, TabContent, PositionalTabContent, RubyContent, RubyAlign, RubyProperties, SymbolContent, FootnoteRefContent, EndnoteRefContent, FieldContent, InlineImageContent, CarriageReturnContent, NoBreakHyphenContent, SoftHyphenContent, LastRenderedPageBreakContent, AnnotationReferenceContent, PageNumberType, DateFieldContent, Run, RevisionInfo, InsertedRun, DeletedRun, MovedFromRun, MovedToRun, MoveRangeMarker, CustomXmlTrackingMarker, ParagraphPropertyChange, RunPropertyChange, SectionPropertyChange, TableRowRevision, CommentDef, CommentRangeStart, CommentRangeEnd, CommentReference, Alignment, LineSpacingRule, LineSpacing, Indentation, TabStopType, TabStopLeader, TabStop, PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader, ParagraphBorders, NumberingRef, FrameAnchorType, DropCapType, ParagraphFrame, ParagraphProperties, Paragraph, Hyperlink, BookmarkStart, BookmarkEnd, ParagraphChild, TableWidth, TableBorders, TableCellMargins, TableLayout, TableLook, TableFloat, TableProperties, RowHeightRule, TableRowProperties, VerticalCellAlign, TextDirection, VerticalMerge, TableCellProperties, TableCell, TableRow, Table, HorizontalPositionRelative, VerticalPositionRelative, WrapStyle, WrapTextSide, WrapMargins, FloatingImage, DrawingShape, PresetShapeType, Chart, ChartType, ChartSeries, ChartLegendPosition, ChartAxis, ChartContent, AltChunk, WebSettings, PersonInfo, NoteType, TablePropertyChange, TableRowPropertyChange, TableCellPropertyChange, CellMergeRevision, OpaquePart, OpaqueRelationship, OpaqueDrawing, TableOfContents, MathRun, MathFraction, MathSuperScript, MathSubScript, MathSubSuperScript, MathPreSubSuperScript, MathPhantom, MathGroupChar, MathBorderBox, MathRadical, MathDelimiter, MathNary, MathFunction, MathLimit, MathMatrix, MathAccent, MathBar, MathBox, MathEquationArray, MathContent, MathBlock, TextBox, CheckBox, SdtListItem, SdtDateProperties, SdtProperties, SdtDataBinding, SdtCheckboxProperties, SdtRepeatingSectionProperties, StructuredDocumentTag, CustomXmlPart, BodyContent, StyleType, TableStyleConditionType, TableStyleConditionalFormat, StyleDef, DocDefaults, NumberFormat, LevelJustification, LevelSuffix, NumberingLevel, MultiLevelType, AbstractNumbering, LevelOverride, NumberingInstance, NumPicBullet, HeaderFooterContent, HeaderDef, FooterDef, FootnoteDef, EndnoteDef, ImageMediaType, ImageDef, FontFamily, FontPitch, FontDef, EmbeddedFont, ProtectionType, HyphenationSettings, DocumentSettings, CompatSetting, CompatFlag, DocumentBackground, DocumentTheme, ThemeColorScheme, ThemeFontScheme, ThemeFont, ThemeFormatScheme, ThemeColorName, CustomPropertyValue, CustomProperty, CoreProperties, AppProperties, DocxDocument, DocxOptions } from "./types.js";
+export { DocxError, DocxParseError, DocxWriteError, DocxMissingPartError, DocxInvalidStructureError, DocxUnsupportedFeatureError, isDocxError } from "./errors.js";
+export { inchesToTwips, twipsToInches, cmToTwips, twipsToCm, ptToTwips, twipsToPt, mmToTwips, inchesToEmu, emuToInches, cmToEmu, emuToCm, ptToEmu, pxToEmu, emuToPx, ptToHalfPoint, halfPointToPt, ptToEighthPoint, eighthPointToPt, lineMultiplierToSpacing, spacingToLineMultiplier, percentToTablePct, tablePctToPercent } from "./units.js";
+export { DocumentBuilder, text, bold, italic, pageBreak, lineBreak, columnBreak, tab, positionalTab, ruby, carriageReturn, noBreakHyphen, softHyphen, field, pageNumberField, totalPagesField, sectionPagesField, sectionField, dateField, sequenceField, timeField, authorField, titleField, subjectField, keywordsField, fileNameField, fileSizeField, styleRefField, refField, pageRefField, noteRefField, hyperlinkField, quoteField, tocField, tcField, indexEntryField, indexField, ifField, includeTextField, includePictureField, formTextField, formCheckboxField, formDropdownField, paragraph, textParagraph, heading, hyperlink, bookmarkStart, bookmarkEnd, commentRangeStart, commentRangeEnd, commentReference, insertedRun, deletedRun, movedFromRun, movedToRun, moveFromRangeStart, moveFromRangeEnd, moveToRangeStart, moveToRangeEnd, checkBox, mathBlock, mathRun, mathFraction, mathSqrt, mathRoot, mathSum, mathIntegral, mathProduct, mathSuperScript, mathSubScript, mathSubSuperScript, mathPreSubSuperScript, mathPhantom, mathGroupChar, mathBorderBox, mathDelimiter, mathNary, mathFunction, mathLimit, mathMatrix, mathAccent, mathBar, mathBox, mathEquationArray, symbol, floatingImage, drawingShape, chart, structuredDocumentTag, border, gridBorders, cell, row, table, simpleTable, searchText, replaceText, resolveThemeColor, patchDocument, mailMerge, paragraphCount, countWords, getHeadings, findBookmark, findComment, listImages, listTables, listHyperlinks, tableCount, extractText } from "./document.js";
+export type { SearchResult, PatchContent, PatchOperation, PatchOptions, DocumentHeading } from "./document.js";
+export { packageDocx } from "./docx-packager.js";
+export { readDocx } from "./docx-reader.js";
+export { deobfuscateFont, obfuscateFont, generateFontKey } from "./font-obfuscation.js";
+export { isEncryptedDocx, verifyPassword, decryptPackage, parseEncryptionInfoXml, deriveEncryptionKey, AGILE_BLOCK_KEYS } from "./encryption.js";
+export type { AgileEncryptionInfo } from "./encryption.js";
+export { hasDigitalSignatures, parseSignatureXml, extractSignatures, isWellFormedSignature } from "./digital-signatures.js";
+export type { DigitalSignatureInfo } from "./digital-signatures.js";
+export { renderToHtml } from "./html-renderer.js";
+export type { HtmlRenderOptions, HtmlRenderResult } from "./html-renderer.js";

package/dist/types/modules/word/index.browser.d.ts

@@ -0,0 +1,4 @@
+/**
+ * DOCX Module - Browser Entry Point
+ */
+export * from "./index.base.js";

package/dist/types/modules/word/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * DOCX Module - Node.js Entry Point
+ */
+export * from "./index.base.js";

package/dist/types/modules/word/internal-utils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * DOCX Module - Internal utilities (shared helpers)
+ */
+/**
+ * Encode a byte array to base64. Uses native Node `Buffer` if available;
+ * otherwise falls back to chunked `btoa()` for browser environments.
+ *
+ * The chunked approach avoids the O(n²) string concatenation cost that naïve
+ * `String.fromCharCode(...data)` implementations exhibit on large buffers.
+ */
+export declare function bytesToBase64(data: Uint8Array): string;
+/**
+ * Decode a base64 string to a byte array. Uses native Node `Buffer` if available.
+ */
+export declare function base64ToBytes(s: string): Uint8Array;
+/**
+ * Build an XML attributes object from an array of [name, value] entries,
+ * omitting entries whose value is `undefined` or `false`. Numeric and boolean
+ * values are stringified: `number → String(n)`, `boolean → "1"`.
+ *
+ * Reduces repetitive `if (x !== undefined) attrs["w:x"] = String(x)` patterns.
+ */
+export declare function buildAttrs(entries: ReadonlyArray<[string, string | number | boolean | undefined | null]>): Record<string, string>;

package/dist/types/modules/word/relationships.d.ts

@@ -0,0 +1,31 @@
+/**
+ * DOCX Module - Relationship Manager
+ *
+ * Manages OPC relationships for the DOCX package.
+ * Generates .rels files for package-level and part-level relationships.
+ */
+import type { XmlSink } from "../xml/types.js";
+/** A single OPC relationship. */
+export interface Relationship {
+    readonly id: string;
+    readonly type: string;
+    readonly target: string;
+    readonly targetMode?: "External";
+}
+/**
+ * Manages relationships and generates .rels XML.
+ */
+export declare class RelationshipManager {
+    private readonly _rels;
+    private _nextId;
+    /** Add a relationship and return its assigned rId. */
+    add(type: string, target: string, targetMode?: "External"): string;
+    /** Add a relationship with a specific ID. */
+    addWithId(id: string, type: string, target: string, targetMode?: "External"): void;
+    /** Get all relationships. */
+    get relationships(): readonly Relationship[];
+    /** Get the number of relationships. */
+    get count(): number;
+    /** Render the relationships XML to a sink. */
+    render(xml: XmlSink): void;
+}