@particle-academy/holy-sheet 2.10.1 → 2.11.0

package/dist/index.d.cts

@@ -143,6 +143,8 @@ interface BuilderOptions {
     enclosure?: string;
 }
 
+type SourceKind = "document" | "template";
+
 /**
  * One op from `Agent.diff`, applied by `Agent.reduce`. Mirrors the PHP
  * `HolySheet\Ops\SheetOpSchema` variants: same `type`, same field names.
@@ -264,7 +266,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.10.1";
+declare const VERSION = "2.11.0";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -286,6 +288,22 @@ declare const Agent: {
      * schema. Throws `UnsupportedFormatException` for anything else.
      */
     read(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
+    /**
+     * Turn an Excel `.xltx` / LibreOffice `.ots` template into its `.xlsx` /
+     * `.ods` twin, or back. `to` is `"document"`, `"template"`, or null to flip.
+     * Universal and synchronous: bytes in, bytes out. Mirrors PHP
+     * `Agent::convertTemplate()`.
+     *
+     * Only the declaration moves: the workbook part's content type in
+     * `[Content_Types].xml`, or the ODF `mimetype` entry together with the
+     * manifest's root media-type (ODF 1.3 requires them to agree). Every other
+     * member is copied as its original zip record, byte for byte.
+     *
+     * Throws `OfficeTemplateRefused` (macro-enabled, mismatched, already that
+     * kind), `ArchiveRefused` (archive guard), or `UnsupportedFormatException`
+     * for a package that is not a spreadsheet.
+     */
+    convertTemplate(input: Uint8Array | ArrayBuffer, to?: SourceKind | null): Uint8Array;
     /** Round-trip an xlsx or ods file on disk back to a schema (Node only). */
     describe(path: string): Promise<Record<string, unknown>>;
     /** Validate + conservative repairs in one call. */
@@ -342,13 +360,15 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.10.1";
+    static readonly VERSION = "2.11.0";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;
     toolDefinition(): Record<string, unknown>;
     read(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
     describe(path: string): Promise<Record<string, unknown>>;
+    /** {@link Agent.convertTemplate}: .xltx/.ots to .xlsx/.ods and back. */
+    convertTemplate(input: Uint8Array | ArrayBuffer, to?: "document" | "template" | null): Uint8Array;
     validateAndRepair(schema: Any$5): RepairResult;
     fromArray(rows: Any$5[][], headers?: string[] | null, sheetName?: string, options?: BuilderOptions): HolySheetSchema;
     fromCsv(csv: string, options?: BuilderOptions): HolySheetSchema;
@@ -357,6 +377,30 @@ declare class HolySheet {
     static version(): string;
 }
 
+/** Bounded archive/security refusal; contains no document names or content. */
+declare class ArchiveRefused extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * An Office or LibreOffice template package refused, with a constant `reason`.
+ * Mirrors PHP `OfficeTemplateRefused`:
+ *
+ * - `macro_enabled`   an .xltm (or a template carrying a VBA project). Never read
+ *                     and never converted.
+ * - `family_mismatch` it declares a template of another family, or its parts
+ *                     are not the family it declares.
+ * - `already_template` / `already_document`  conversion asked for what it is.
+ * - `not_convertible` there is no single declaration that can be rewritten.
+ * - `odf_mimetype`    an ODF package whose `mimetype` is not first and stored.
+ * - `bad_target`      the conversion target is not `document` or `template`.
+ *
+ * Branch on `reason`; the message is for people.
+ */
+declare class OfficeTemplateRefused extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
 /** Thrown when a Holy Sheet schema fails validation. Mirrors PHP `SchemaException`. */
 declare class SchemaException extends Error {
     readonly errors: ValidationError[];
@@ -382,6 +426,14 @@ declare class UnsupportedFormatException extends Error {
     static unknownPackage(path: string | null, mimetype: string | null): UnsupportedFormatException;
 }
 
+interface ArchiveLimits {
+    maxArchiveBytes?: number;
+    maxEntries?: number;
+    maxPartBytes?: number;
+    maxExpandedBytes?: number;
+    maxCompressionRatio?: number;
+}
+
 type Any$4 = any;
 /** Hand-rolled schema validator. Mirrors PHP `Schema\Validator`. */
 declare class Validator {
@@ -564,7 +616,11 @@ declare class Sheet {
 declare class Workbook {
     readonly sheets: Sheet[];
     readonly meta: Record<string, unknown>;
-    constructor(sheets: Sheet[], meta?: Record<string, unknown>);
+    /** What a reader found: an .xltx / .ots reads exactly like its .xlsx / .ods twin and is marked `template`. */
+    readonly sourceKind: "document" | "template";
+    constructor(sheets: Sheet[], meta?: Record<string, unknown>, 
+    /** What a reader found: an .xltx / .ots reads exactly like its .xlsx / .ods twin and is marked `template`. */
+    sourceKind?: "document" | "template");
 }
 
 type Any$2 = any;
@@ -909,6 +965,7 @@ interface ZipFile {
 }
 declare function zipSync(files: ZipFile[]): Uint8Array;
 
-declare function unzipSync(data: Uint8Array): Record<string, Uint8Array>;
+/** STORE/DEFLATE reader with metadata, CRC, duplicate and expansion checks. */
+declare function unzipSync(data: Uint8Array, limits?: ArchiveLimits): Record<string, Uint8Array>;
 
-export { type AddSheetOp, Agent, type AggOp, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ChartSchema, type ClearCellOp, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DeleteColumnsOp, type DeleteRowsOp, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, type InsertColumnsOp, type InsertRowsOp, type MoveSheetOp, Normalizer, OdsReader, type RemoveSheetOp, type RenameSheetOp, type RepairResult, Repairer, type ReplaceSheetOp, type RowCell, SchemaException, type SetCellOp, type SetColumnWidthsOp, type SetFrozenOp, type SetMergedRegionsOp, type SetMetaOp, type SetRangeOp, type SetWorkbookOp, SheetDiff, type SheetOp, SheetOpSchema, type SheetOpType, SheetReducer, type SheetSchema, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };
+export { type AddSheetOp, Agent, type AggOp, type ArchiveLimits, ArchiveRefused, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ChartSchema, type ClearCellOp, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DeleteColumnsOp, type DeleteRowsOp, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, type InsertColumnsOp, type InsertRowsOp, type MoveSheetOp, Normalizer, OdsReader, OfficeTemplateRefused, type RemoveSheetOp, type RenameSheetOp, type RepairResult, Repairer, type ReplaceSheetOp, type RowCell, SchemaException, type SetCellOp, type SetColumnWidthsOp, type SetFrozenOp, type SetMergedRegionsOp, type SetMetaOp, type SetRangeOp, type SetWorkbookOp, SheetDiff, type SheetOp, SheetOpSchema, type SheetOpType, SheetReducer, type SheetSchema, type SourceKind, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };

package/dist/index.d.ts

@@ -143,6 +143,8 @@ interface BuilderOptions {
     enclosure?: string;
 }
 
+type SourceKind = "document" | "template";
+
 /**
  * One op from `Agent.diff`, applied by `Agent.reduce`. Mirrors the PHP
  * `HolySheet\Ops\SheetOpSchema` variants: same `type`, same field names.
@@ -264,7 +266,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.10.1";
+declare const VERSION = "2.11.0";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -286,6 +288,22 @@ declare const Agent: {
      * schema. Throws `UnsupportedFormatException` for anything else.
      */
     read(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
+    /**
+     * Turn an Excel `.xltx` / LibreOffice `.ots` template into its `.xlsx` /
+     * `.ods` twin, or back. `to` is `"document"`, `"template"`, or null to flip.
+     * Universal and synchronous: bytes in, bytes out. Mirrors PHP
+     * `Agent::convertTemplate()`.
+     *
+     * Only the declaration moves: the workbook part's content type in
+     * `[Content_Types].xml`, or the ODF `mimetype` entry together with the
+     * manifest's root media-type (ODF 1.3 requires them to agree). Every other
+     * member is copied as its original zip record, byte for byte.
+     *
+     * Throws `OfficeTemplateRefused` (macro-enabled, mismatched, already that
+     * kind), `ArchiveRefused` (archive guard), or `UnsupportedFormatException`
+     * for a package that is not a spreadsheet.
+     */
+    convertTemplate(input: Uint8Array | ArrayBuffer, to?: SourceKind | null): Uint8Array;
     /** Round-trip an xlsx or ods file on disk back to a schema (Node only). */
     describe(path: string): Promise<Record<string, unknown>>;
     /** Validate + conservative repairs in one call. */
@@ -342,13 +360,15 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.10.1";
+    static readonly VERSION = "2.11.0";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;
     toolDefinition(): Record<string, unknown>;
     read(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
     describe(path: string): Promise<Record<string, unknown>>;
+    /** {@link Agent.convertTemplate}: .xltx/.ots to .xlsx/.ods and back. */
+    convertTemplate(input: Uint8Array | ArrayBuffer, to?: "document" | "template" | null): Uint8Array;
     validateAndRepair(schema: Any$5): RepairResult;
     fromArray(rows: Any$5[][], headers?: string[] | null, sheetName?: string, options?: BuilderOptions): HolySheetSchema;
     fromCsv(csv: string, options?: BuilderOptions): HolySheetSchema;
@@ -357,6 +377,30 @@ declare class HolySheet {
     static version(): string;
 }
 
+/** Bounded archive/security refusal; contains no document names or content. */
+declare class ArchiveRefused extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * An Office or LibreOffice template package refused, with a constant `reason`.
+ * Mirrors PHP `OfficeTemplateRefused`:
+ *
+ * - `macro_enabled`   an .xltm (or a template carrying a VBA project). Never read
+ *                     and never converted.
+ * - `family_mismatch` it declares a template of another family, or its parts
+ *                     are not the family it declares.
+ * - `already_template` / `already_document`  conversion asked for what it is.
+ * - `not_convertible` there is no single declaration that can be rewritten.
+ * - `odf_mimetype`    an ODF package whose `mimetype` is not first and stored.
+ * - `bad_target`      the conversion target is not `document` or `template`.
+ *
+ * Branch on `reason`; the message is for people.
+ */
+declare class OfficeTemplateRefused extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
 /** Thrown when a Holy Sheet schema fails validation. Mirrors PHP `SchemaException`. */
 declare class SchemaException extends Error {
     readonly errors: ValidationError[];
@@ -382,6 +426,14 @@ declare class UnsupportedFormatException extends Error {
     static unknownPackage(path: string | null, mimetype: string | null): UnsupportedFormatException;
 }
 
+interface ArchiveLimits {
+    maxArchiveBytes?: number;
+    maxEntries?: number;
+    maxPartBytes?: number;
+    maxExpandedBytes?: number;
+    maxCompressionRatio?: number;
+}
+
 type Any$4 = any;
 /** Hand-rolled schema validator. Mirrors PHP `Schema\Validator`. */
 declare class Validator {
@@ -564,7 +616,11 @@ declare class Sheet {
 declare class Workbook {
     readonly sheets: Sheet[];
     readonly meta: Record<string, unknown>;
-    constructor(sheets: Sheet[], meta?: Record<string, unknown>);
+    /** What a reader found: an .xltx / .ots reads exactly like its .xlsx / .ods twin and is marked `template`. */
+    readonly sourceKind: "document" | "template";
+    constructor(sheets: Sheet[], meta?: Record<string, unknown>, 
+    /** What a reader found: an .xltx / .ots reads exactly like its .xlsx / .ods twin and is marked `template`. */
+    sourceKind?: "document" | "template");
 }
 
 type Any$2 = any;
@@ -909,6 +965,7 @@ interface ZipFile {
 }
 declare function zipSync(files: ZipFile[]): Uint8Array;
 
-declare function unzipSync(data: Uint8Array): Record<string, Uint8Array>;
+/** STORE/DEFLATE reader with metadata, CRC, duplicate and expansion checks. */
+declare function unzipSync(data: Uint8Array, limits?: ArchiveLimits): Record<string, Uint8Array>;
 
-export { type AddSheetOp, Agent, type AggOp, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ChartSchema, type ClearCellOp, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DeleteColumnsOp, type DeleteRowsOp, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, type InsertColumnsOp, type InsertRowsOp, type MoveSheetOp, Normalizer, OdsReader, type RemoveSheetOp, type RenameSheetOp, type RepairResult, Repairer, type ReplaceSheetOp, type RowCell, SchemaException, type SetCellOp, type SetColumnWidthsOp, type SetFrozenOp, type SetMergedRegionsOp, type SetMetaOp, type SetRangeOp, type SetWorkbookOp, SheetDiff, type SheetOp, SheetOpSchema, type SheetOpType, SheetReducer, type SheetSchema, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };
+export { type AddSheetOp, Agent, type AggOp, type ArchiveLimits, ArchiveRefused, ArrayBuilder, type BuilderOptions, CellAddress, type CellData, type CellFormatInput, type CellPrimitive, type ChartSchema, type ClearCellOp, type ColumnSchema, type ColumnType, type CommentInput, CsvBuilder, type DeleteColumnsOp, type DeleteRowsOp, type DisplayFormat, FormatSniffer, FormulaLinter, type FormulaProblem, HolySheet, type HolySheetSchema, Inference, type InsertColumnsOp, type InsertRowsOp, type MoveSheetOp, Normalizer, OdsReader, OfficeTemplateRefused, type RemoveSheetOp, type RenameSheetOp, type RepairResult, Repairer, type ReplaceSheetOp, type RowCell, SchemaException, type SetCellOp, type SetColumnWidthsOp, type SetFrozenOp, type SetMergedRegionsOp, type SetMetaOp, type SetRangeOp, type SetWorkbookOp, SheetDiff, type SheetOp, SheetOpSchema, type SheetOpType, SheetReducer, type SheetSchema, type SourceKind, type SpreadsheetFormat, Theme, type ThemeKey, UnsupportedFormatException, VERSION, type ValidationError, Validator, type WriteResult, XlsxReader, XlsxWriter, type ZipFile, unzipSync, zipSync };