@embedpdf/models 2.1.2 → 2.3.0

package/dist/pdf.d.ts

@@ -48,6 +48,19 @@ export interface PdfDocumentObject {
      * Pages in this document
      */
     pages: PdfPageObject[];
+    /**
+     * Whether the document is encrypted
+     */
+    isEncrypted: boolean;
+    /**
+     * Whether owner permissions are currently unlocked
+     */
+    isOwnerUnlocked: boolean;
+    /**
+     * Raw permission flags from FPDF_GetDocPermissions.
+     * Use PdfPermissionFlag to check individual permissions.
+     */
+    permissions: number;
 }
 /**
  * metadata of pdf document
@@ -816,6 +829,35 @@ export declare enum PdfAnnotationLineEnding {
      */
     Unknown = 10
 }
+/**
+ * Reply type of annotation (RT property per ISO 32000-2)
+ *
+ * Specifies how an annotation relates to another annotation when it is
+ * a reply (via IRT - In Reply To). Valid values are:
+ * - Reply (/R): Normal comment reply (default if RT is missing)
+ * - Group (/Group): Logical grouping of annotations
+ *
+ * @public
+ */
+export declare enum PdfAnnotationReplyType {
+    /**
+     * Unknown or invalid reply type
+     */
+    Unknown = 0,
+    /**
+     * /R - Comment reply (default if RT is missing)
+     * The annotation is a child comment of the annotation referenced by IRT.
+     * Used for comment threads, reviewer discussions, sticky-note replies.
+     */
+    Reply = 1,
+    /**
+     * /Group - Logical grouping
+     * The annotation is grouped with the annotation referenced by IRT.
+     * They represent the same logical object. Used when multiple annotations
+     * act as one unit (e.g., visual shape + metadata/label).
+     */
+    Group = 2
+}
 /**
  * Basic information of pdf annotation
  *
@@ -870,6 +912,14 @@ export interface PdfAnnotationObjectBase {
      * Custom data of the annotation
      */
     custom?: any;
+    /**
+     * In reply to annotation id (IRT - for grouping or reply threads)
+     */
+    inReplyToId?: string;
+    /**
+     * Reply type (how this annotation relates to the parent via IRT)
+     */
+    replyType?: PdfAnnotationReplyType;
 }
 /**
  * Popup annotation
@@ -887,10 +937,6 @@ export interface PdfPopupAnnoObject extends PdfAnnotationObjectBase {
      * Whether the popup is opened or not
      */
     open: boolean;
-    /**
-     * In reply to id
-     */
-    inReplyToId?: string;
 }
 /**
  * Pdf Link annotation
@@ -904,6 +950,22 @@ export interface PdfLinkAnnoObject extends PdfAnnotationObjectBase {
      * target of the link
      */
     target: PdfLinkTarget | undefined;
+    /**
+     * Stroke color of the link border (e.g., "#00A5E4")
+     */
+    strokeColor?: string;
+    /**
+     * Width of the link border (default: 2)
+     */
+    strokeWidth?: number;
+    /**
+     * Style of the link border (default: UNDERLINE)
+     */
+    strokeStyle?: PdfAnnotationBorderStyle;
+    /**
+     * Dash pattern for dashed border style
+     */
+    strokeDashArray?: number[];
 }
 /**
  * Pdf Text annotation
@@ -925,10 +987,6 @@ export interface PdfTextAnnoObject extends PdfAnnotationObjectBase {
      * opacity of text annotation
      */
     opacity?: number;
-    /**
-     * In reply to id
-     */
-    inReplyToId?: string;
     /**
      * State of the text annotation
      */
@@ -1195,9 +1253,13 @@ export interface PdfInkAnnoObject extends PdfAnnotationObjectBase {
      */
     inkList: PdfInkListObject[];
     /**
-     * color of ink annotation
+     * Color of the ink stroke (preferred over deprecated `color`)
      */
-    color: string;
+    strokeColor?: string;
+    /**
+     * @deprecated Use strokeColor instead. Will be removed in next major version.
+     */
+    color?: string;
     /**
      * opacity of ink annotation
      */
@@ -1351,9 +1413,13 @@ export interface PdfHighlightAnnoObject extends PdfAnnotationObjectBase {
      */
     contents?: string;
     /**
-     * color of highlight annotation
+     * Color of the highlight markup (preferred over deprecated `color`)
      */
-    color: string;
+    strokeColor?: string;
+    /**
+     * @deprecated Use strokeColor instead. Will be removed in next major version.
+     */
+    color?: string;
     /**
      * opacity of highlight annotation
      */
@@ -1595,19 +1661,23 @@ export interface PdfSquigglyAnnoObject extends PdfAnnotationObjectBase {
     /** {@inheritDoc PdfAnnotationObjectBase.type} */
     type: PdfAnnotationSubtype.SQUIGGLY;
     /**
-     * Text contents of the highlight annotation
+     * Text contents of the squiggly annotation
      */
     contents?: string;
     /**
-     * color of strike out annotation
+     * Color of the squiggly markup (preferred over deprecated `color`)
      */
-    color: string;
+    strokeColor?: string;
     /**
-     * opacity of strike out annotation
+     * @deprecated Use strokeColor instead. Will be removed in next major version.
+     */
+    color?: string;
+    /**
+     * opacity of squiggly annotation
      */
     opacity: number;
     /**
-     * quads of highlight area
+     * quads of squiggly area
      */
     segmentRects: Rect[];
 }
@@ -1620,19 +1690,23 @@ export interface PdfUnderlineAnnoObject extends PdfAnnotationObjectBase {
     /** {@inheritDoc PdfAnnotationObjectBase.type} */
     type: PdfAnnotationSubtype.UNDERLINE;
     /**
-     * Text contents of the highlight annotation
+     * Text contents of the underline annotation
      */
     contents?: string;
     /**
-     * color of strike out annotation
+     * Color of the underline markup (preferred over deprecated `color`)
      */
-    color: string;
+    strokeColor?: string;
     /**
-     * opacity of strike out annotation
+     * @deprecated Use strokeColor instead. Will be removed in next major version.
+     */
+    color?: string;
+    /**
+     * opacity of underline annotation
      */
     opacity: number;
     /**
-     * quads of highlight area
+     * quads of underline area
      */
     segmentRects: Rect[];
 }
@@ -1649,15 +1723,19 @@ export interface PdfStrikeOutAnnoObject extends PdfAnnotationObjectBase {
      */
     contents?: string;
     /**
-     * color of strike out annotation
+     * Color of the strikeout markup (preferred over deprecated `color`)
      */
-    color: string;
+    strokeColor?: string;
+    /**
+     * @deprecated Use strokeColor instead. Will be removed in next major version.
+     */
+    color?: string;
     /**
      * opacity of strike out annotation
      */
     opacity: number;
     /**
-     * quads of highlight area
+     * quads of strikeout area
      */
     segmentRects: Rect[];
 }
@@ -1707,7 +1785,11 @@ export interface PdfFreeTextAnnoObject extends PdfAnnotationObjectBase {
      */
     opacity: number;
     /**
-     * Background color of the free text annotation
+     * Background/fill color of the free text annotation (matches shape convention)
+     */
+    color?: string;
+    /**
+     * @deprecated Use color instead. Will be removed in next major version.
      */
     backgroundColor?: string;
     /**
@@ -2054,15 +2136,53 @@ export interface PdfAnnotationTransformation {
  * @public
  */
 export type PdfFileContent = ArrayBuffer;
-export declare enum PdfPermission {
-    PrintDocument = 8,
-    ModifyContent = 16,
-    CopyOrExtract = 32,
-    AddOrModifyTextAnnot = 64,
-    FillInExistingForm = 512,
-    ExtractTextOrGraphics = 1024,
-    AssembleDocument = 2048,
-    PrintHighQuality = 4096
+/**
+ * PDF permission flags per ISO 32000-1 Table 22
+ * These are the flags to pass to setDocumentEncryption indicating what actions ARE ALLOWED.
+ * Use buildPermissions() helper to combine flags.
+ *
+ * @public
+ */
+export declare enum PdfPermissionFlag {
+    /** Bit 3: Print (possibly degraded quality) */
+    Print = 4,
+    /** Bit 4: Modify document contents */
+    ModifyContents = 8,
+    /** Bit 5: Copy/extract text and graphics */
+    CopyContents = 16,
+    /** Bit 6: Add/modify annotations, fill forms */
+    ModifyAnnotations = 32,
+    /** Bit 9: Fill in existing form fields */
+    FillForms = 256,
+    /** Bit 10: Extract for accessibility */
+    ExtractForAccessibility = 512,
+    /** Bit 11: Assemble document (insert, rotate, delete pages) */
+    AssembleDocument = 1024,
+    /** Bit 12: High quality print */
+    PrintHighQuality = 2048,
+    /** Common combination: Allow all permissions */
+    AllowAll = 3900
+}
+/**
+ * Helper function to combine permission flags for setDocumentEncryption.
+ * Note: PrintHighQuality automatically includes Print (enforced in C++ layer as well).
+ *
+ * @param flags - Permission flags to combine
+ * @returns Combined permission flags as a number
+ *
+ * @public
+ */
+export declare function buildPermissions(...flags: PdfPermissionFlag[]): number;
+/**
+ * Error thrown when a permission check fails.
+ *
+ * @public
+ */
+export declare class PermissionDeniedError extends Error {
+    readonly requiredFlags: PdfPermissionFlag[];
+    readonly currentPermissions: number;
+    readonly name = "PermissionDeniedError";
+    constructor(requiredFlags: PdfPermissionFlag[], currentPermissions: number);
 }
 export declare enum PdfPageFlattenFlag {
     Display = 0,
@@ -2634,6 +2754,43 @@ export interface PdfEngine<T = Blob> {
      * @returns task that all documents are closed or not
      */
     closeAllDocuments: () => PdfTask<boolean>;
+    /**
+     * Sets AES-256 encryption on a document.
+     * Must be called before saveAsCopy() for encryption to take effect.
+     * @param doc - pdf document
+     * @param userPassword - Password to open document (empty = no open password)
+     * @param ownerPassword - Password to change permissions (required)
+     * @param allowedFlags - OR'd PdfPermissionFlag values indicating allowed actions
+     * @returns task indicating success or failure
+     */
+    setDocumentEncryption: (doc: PdfDocumentObject, userPassword: string, ownerPassword: string, allowedFlags: number) => PdfTask<boolean>;
+    /**
+     * Marks document for encryption removal on save.
+     * Call this to remove password protection when saving.
+     * @param doc - pdf document
+     * @returns task indicating success
+     */
+    removeEncryption: (doc: PdfDocumentObject) => PdfTask<boolean>;
+    /**
+     * Attempt to unlock owner permissions on an encrypted document.
+     * Call this after opening a document with user-level access to gain full permissions.
+     * @param doc - pdf document
+     * @param ownerPassword - the owner password
+     * @returns task that indicates whether unlock succeeded
+     */
+    unlockOwnerPermissions: (doc: PdfDocumentObject, ownerPassword: string) => PdfTask<boolean>;
+    /**
+     * Check if a document is encrypted.
+     * @param doc - pdf document
+     * @returns task that resolves to true if the document is encrypted
+     */
+    isEncrypted: (doc: PdfDocumentObject) => PdfTask<boolean>;
+    /**
+     * Check if owner permissions are currently unlocked.
+     * @param doc - pdf document
+     * @returns task that resolves to true if owner permissions are unlocked
+     */
+    isOwnerUnlocked: (doc: PdfDocumentObject) => PdfTask<boolean>;
 }
 /**
  * Method name of PdfEngine interface
@@ -2708,6 +2865,11 @@ export interface IPdfiumExecutor {
     saveAsCopy(doc: PdfDocumentObject): PdfTask<ArrayBuffer>;
     closeDocument(doc: PdfDocumentObject): PdfTask<boolean>;
     closeAllDocuments(): PdfTask<boolean>;
+    setDocumentEncryption(doc: PdfDocumentObject, userPassword: string, ownerPassword: string, allowedFlags: number): PdfTask<boolean>;
+    removeEncryption(doc: PdfDocumentObject): PdfTask<boolean>;
+    unlockOwnerPermissions(doc: PdfDocumentObject, ownerPassword: string): PdfTask<boolean>;
+    isEncrypted(doc: PdfDocumentObject): PdfTask<boolean>;
+    isOwnerUnlocked(doc: PdfDocumentObject): PdfTask<boolean>;
 }
 /**
  * Arguments of PdfEngine method

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embedpdf/models",
-  "version": "2.1.2",
+  "version": "2.3.0",
   "private": false,
   "description": "Shared type definitions, data models, and utility helpers (geometry, tasks, logging, PDF primitives) that underpin every package in the EmbedPDF ecosystem.",
   "type": "module",