@hussmartinez/pdf-sdk 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -130,6 +130,60 @@ export declare function linkDestination(url: string): string | undefined;
130
130
  */
131
131
  export declare const PDF_MAX_CANVAS_PIXELS = 16777216;
132
132
 
133
+ /**
134
+ * The most Unicode code points in a form field's name.
135
+ *
136
+ * @public
137
+ */
138
+ export declare const PDF_MAX_FIELD_NAME_LENGTH = 1000;
139
+
140
+ /**
141
+ * The most Unicode code points in a page key, a source id or an annotation
142
+ * id. Lengths count code points, not UTF-16 units (sdk-core ADR 0045).
143
+ *
144
+ * @public
145
+ */
146
+ export declare const PDF_MAX_ID_LENGTH = 128;
147
+
148
+ /**
149
+ * The most points in one pen or highlighter stroke.
150
+ *
151
+ * @public
152
+ */
153
+ export declare const PDF_MAX_STROKE_POINTS = 10000;
154
+
155
+ /**
156
+ * The most Unicode code points in a text note, or a form field's text value.
157
+ *
158
+ * @public
159
+ */
160
+ export declare const PDF_MAX_TEXT_LENGTH = 10000;
161
+
162
+ /**
163
+ * The name of the plan's portable format (sdk-core ADR 0045).
164
+ *
165
+ * @public
166
+ */
167
+ export declare const PDF_PLAN_FORMAT = "hm-pdf-plan";
168
+
169
+ /**
170
+ * The version of {@link PDF_PLAN_FORMAT} this release writes, and the latest
171
+ * it reads.
172
+ *
173
+ * @public
174
+ */
175
+ export declare const PDF_PLAN_VERSION = 1;
176
+
177
+ /**
178
+ * The grid positions and sizes on a page are kept on: millionths of the
179
+ * page (sdk-core ADR 0045, docs/adr/0003). Every position, size, stroke
180
+ * width and text size the session stores is a whole number of millionths,
181
+ * so a document saved in any language reproduces it exactly.
182
+ *
183
+ * @public
184
+ */
185
+ export declare const PDF_POSITION_GRID = 1000000;
186
+
133
187
  /**
134
188
  * Adds an annotation to a page.
135
189
  *
@@ -144,6 +198,19 @@ export declare interface PdfAddAnnotationCommand {
144
198
  readonly index?: number;
145
199
  }
146
200
 
201
+ /**
202
+ * `pdf.addAnnotation` as `hm-pdf-command` writes it, with the annotation's
203
+ * positions and sizes in whole millionths of the page.
204
+ *
205
+ * @public
206
+ */
207
+ export declare interface PdfAddAnnotationCommandDocument {
208
+ readonly type: "pdf.addAnnotation";
209
+ readonly page: string;
210
+ readonly annotation: PdfAnnotationDocument;
211
+ readonly index?: number;
212
+ }
213
+
147
214
  /**
148
215
  * Anything the editor draws on top of a page until it's flattened on export
149
216
  * (ADR 0003). Annotations are plain data, so they can be stored in commands
@@ -153,6 +220,29 @@ export declare interface PdfAddAnnotationCommand {
153
220
  */
154
221
  export declare type PdfAnnotation = PdfStrokeAnnotation | PdfTextAnnotation | PdfImageAnnotation;
155
222
 
223
+ /**
224
+ * An annotation in a plan document. Version 1 has no signatures: their image
225
+ * needs an asset, whose design comes with the signature tool (docs/adr/0003).
226
+ *
227
+ * @public
228
+ */
229
+ export declare type PdfAnnotationDocument = PdfStrokeAnnotationDocument | PdfTextAnnotationDocument;
230
+
231
+ /**
232
+ * A content-addressed reference to binary data, such as a source's file
233
+ * (sdk-core ADR 0045). Documents never inline bytes.
234
+ *
235
+ * @public
236
+ */
237
+ export declare interface PdfAssetReference {
238
+ /** `sha256:` and the lowercase hex SHA-256 of the bytes. */
239
+ readonly asset: string;
240
+ /** The bytes' media type, such as `application/pdf`, in lowercase. */
241
+ readonly mediaType: string;
242
+ /** The size of the bytes. */
243
+ readonly size: number;
244
+ }
245
+
156
246
  /**
157
247
  * Everything needed to build an output document from the page plan, in one
158
248
  * call to the processor (ADR 0003): the sources, the pages in order, and the
@@ -252,7 +342,7 @@ export declare interface PdfCallOptions {
252
342
  }
253
343
 
254
344
  /**
255
- * A colour as `#rrggbb`.
345
+ * A colour as `#rrggbb`, in lowercase.
256
346
  *
257
347
  * @public
258
348
  */
@@ -267,6 +357,56 @@ export declare type PdfColor = `#${string}`;
267
357
  */
268
358
  export declare type PdfCommand = PdfRotatePagesCommand | PdfDeletePagesCommand | PdfRestorePagesCommand | PdfMovePagesCommand | PdfReorderPagesCommand | PdfInsertPagesCommand | PdfSetFieldValueCommand | PdfAddAnnotationCommand | PdfRemoveAnnotationCommand;
269
359
 
360
+ /**
361
+ * A user-level command as portable JSON: `hm-pdf-command` version 1, which
362
+ * `formats/hm-pdf-command/v1.schema.json` describes. Every command but
363
+ * `pdf.restorePages`, an inverse that carries whole pages; only
364
+ * `pdf.addAnnotation` differs from the command in memory.
365
+ *
366
+ * @public
367
+ */
368
+ export declare type PdfCommandDocument = Exclude<PdfCommand, PdfRestorePagesCommand | PdfAddAnnotationCommand> | PdfAddAnnotationCommandDocument;
369
+
370
+ /**
371
+ * Why a command was refused, as a stable token: `details.reason` on the
372
+ * `INVALID_COMMAND` error (sdk-core ADR 0045).
373
+ *
374
+ * - `malformed-command`: not shaped as a command of its type, such as a
375
+ * missing field, a field of the wrong type, an unknown field, an empty
376
+ * list of pages, or an id that's empty or over `PDF_MAX_ID_LENGTH` code
377
+ * points.
378
+ * - `unknown-command`: a `type` the session doesn't know.
379
+ * - `unknown-page`: a page key the plan doesn't have.
380
+ * - `duplicate-page`: a page named twice in one command.
381
+ * - `last-page`: deleting every page; a document keeps at least one.
382
+ * - `invalid-position`: a position outside the plan, or outside a page's
383
+ * annotations.
384
+ * - `invalid-rotation`: an angle that isn't a multiple of 90 degrees from
385
+ * -360 to 360, or a page rotation other than 0, 90, 180 or 270.
386
+ * - `invalid-order`: a new order that doesn't list every page exactly once.
387
+ * - `invalid-keys`: an insert without one key per page.
388
+ * - `duplicate-key`: a new page key the plan already has, or one given twice.
389
+ * - `unknown-source`: a source the session doesn't hold.
390
+ * - `page-out-of-range`: a page index its source doesn't have.
391
+ * - `field-name-too-long`: a form field's name over
392
+ * `PDF_MAX_FIELD_NAME_LENGTH` code points.
393
+ * - `text-too-long`: a text note, or a field's text value, over
394
+ * `PDF_MAX_TEXT_LENGTH` code points.
395
+ * - `unknown-annotation`: an annotation id the page doesn't have.
396
+ * - `duplicate-annotation`: an annotation id the page already has.
397
+ * - `unsupported-annotation`: an annotation type the session doesn't edit,
398
+ * such as `signature`, whose image the portable format can't carry yet.
399
+ * - `outside-page`: a position outside the page, 0 to 1 on each axis.
400
+ * - `invalid-size`: a stroke width or text size that isn't more than 0 and
401
+ * at most 1, after snapping to `PDF_POSITION_GRID`.
402
+ * - `too-many-points`: a stroke with no points, or over
403
+ * `PDF_MAX_STROKE_POINTS`.
404
+ * - `invalid-color`: a colour that isn't `#rrggbb` in lowercase.
405
+ *
406
+ * @public
407
+ */
408
+ export declare type PdfCommandRejection = "malformed-command" | "unknown-command" | "unknown-page" | "duplicate-page" | "last-page" | "invalid-position" | "invalid-rotation" | "invalid-order" | "invalid-keys" | "duplicate-key" | "unknown-source" | "page-out-of-range" | "field-name-too-long" | "text-too-long" | "unknown-annotation" | "duplicate-annotation" | "unsupported-annotation" | "outside-page" | "invalid-size" | "too-many-points" | "invalid-color";
409
+
270
410
  /**
271
411
  * How to compress the output. Compression is lossless unless `images` is set.
272
412
  *
@@ -330,6 +470,37 @@ export declare interface PdfDocumentHandle {
330
470
  destroy(): Promise<void>;
331
471
  }
332
472
 
473
+ /**
474
+ * A point in a plan document: whole millionths of the page, from 0 to
475
+ * {@link PDF_POSITION_GRID}.
476
+ *
477
+ * @public
478
+ */
479
+ export declare interface PdfDocumentPoint {
480
+ readonly x: number;
481
+ readonly y: number;
482
+ }
483
+
484
+ /**
485
+ * Why a plan document was refused, as a stable token: `details.reason` on
486
+ * the error (sdk-core ADR 0045).
487
+ *
488
+ * - With `UNSUPPORTED_FORMAT`: `unknown-format`, a document of another
489
+ * format, and `unknown-format-version`, a later version than this release
490
+ * reads.
491
+ * - With `INVALID_DOCUMENT`: `malformed-document`, a document that isn't
492
+ * shaped as the schema says; `unknown-source`, a page or form values for a
493
+ * source the document doesn't list; `page-out-of-range`, a page index its
494
+ * source doesn't have; `duplicate-key`, two pages with one key;
495
+ * `duplicate-annotation`, two annotations with one id on a page; and, as
496
+ * for commands, `invalid-rotation`, `outside-page`, `invalid-size`,
497
+ * `too-many-points`, `invalid-color`, `unsupported-annotation`,
498
+ * `field-name-too-long` and `text-too-long`.
499
+ *
500
+ * @public
501
+ */
502
+ export declare type PdfDocumentRejection = "unknown-format" | "unknown-format-version" | "malformed-document" | "unknown-source" | "page-out-of-range" | "duplicate-key" | "duplicate-annotation" | "invalid-rotation" | "outside-page" | "invalid-size" | "too-many-points" | "invalid-color" | "unsupported-annotation" | "field-name-too-long" | "text-too-long";
503
+
333
504
  /**
334
505
  * How to encrypt the output. Encryption is always AES-256.
335
506
  *
@@ -406,13 +577,21 @@ export declare class PdfError extends SdkError<PdfErrorCode> {
406
577
  * - `IMAGE_TOO_LARGE`: an image exceeds the `maxImagePixels` limit. It's
407
578
  * reported as a warning, because the image is skipped rather than the
408
579
  * document failing (ADR 0004).
580
+ * - `INVALID_COMMAND`: an edit command doesn't apply to the plan, such as
581
+ * one naming a page the plan doesn't have. `details.reason` says why, as
582
+ * a stable token (`PdfCommandRejection`, sdk-core ADR 0045).
583
+ * - `INVALID_DOCUMENT`: a plan document, such as a saved project, isn't
584
+ * valid in its format. `details.reason` says why (`PdfDocumentRejection`).
585
+ * - `UNSUPPORTED_FORMAT`: a plan document of another format, or of a later
586
+ * version than this release reads, with `details.reason`
587
+ * `unknown-format` or `unknown-format-version`.
409
588
  *
410
589
  * Limit codes carry `details` with the `limit`, its `maximum`, the `actual`
411
590
  * value and the `unit`.
412
591
  *
413
592
  * @public
414
593
  */
415
- export declare type PdfErrorCode = SdkCoreErrorCode | "INVALID_PDF" | "PASSWORD_REQUIRED" | "PROCESSING_FAILED" | "TOO_MANY_PAGES" | "SESSION_TOO_LARGE" | "IMAGE_TOO_LARGE";
594
+ export declare type PdfErrorCode = SdkCoreErrorCode | "INVALID_PDF" | "PASSWORD_REQUIRED" | "PROCESSING_FAILED" | "TOO_MANY_PAGES" | "SESSION_TOO_LARGE" | "IMAGE_TOO_LARGE" | "INVALID_COMMAND" | "INVALID_DOCUMENT" | "UNSUPPORTED_FORMAT";
416
595
 
417
596
  /**
418
597
  * Options for {@link PdfSession.export}.
@@ -481,6 +660,10 @@ export declare interface PdfFormField {
481
660
  /**
482
661
  * A drawn signature, or another image, placed on the page.
483
662
  *
663
+ * The session refuses it for now, with `INVALID_COMMAND` and
664
+ * `unsupported-annotation`: the portable format can't carry its image yet
665
+ * (docs/adr/0003). The editor's signature tool will bring it back.
666
+ *
484
667
  * @public
485
668
  */
486
669
  export declare interface PdfImageAnnotation {
@@ -696,6 +879,9 @@ export declare const pdfMessages: {
696
879
  readonly "errors.TOO_MANY_PAGES": "This document has {actual, number} pages, which is over the {maximum, number}-page limit.";
697
880
  readonly "errors.SESSION_TOO_LARGE": "The open documents would use {actual, fileSize}, which is over the {maximum, fileSize} limit. Close a document, or clear the undo history, and try again.";
698
881
  readonly "errors.IMAGE_TOO_LARGE": "Some images are too large to show. They're kept unchanged in the document.";
882
+ readonly "errors.INVALID_COMMAND": "This edit couldn't be made. Please try again.";
883
+ readonly "errors.INVALID_DOCUMENT": "This project is damaged, or it isn't a PDF project.";
884
+ readonly "errors.UNSUPPORTED_FORMAT": "This project was saved by a newer version, or by another app. Update the app, and try again.";
699
885
  readonly "warnings.maxPages": {
700
886
  readonly $plural: "actual";
701
887
  } & {
@@ -726,6 +912,24 @@ export declare const pdfMessages: {
726
912
  readonly other: "Opened a PDF with {count} pages.";
727
913
  };
728
914
  readonly "editor.closed": "The PDF was closed.";
915
+ readonly "editor.undone": "Undone.";
916
+ readonly "editor.redone": "Redone.";
917
+ readonly "editor.rotated": {
918
+ readonly $plural: "count";
919
+ } & {
920
+ readonly one: "Rotated {count} page.";
921
+ readonly other: "Rotated {count} pages.";
922
+ };
923
+ readonly "toolbar.label": "PDF tools";
924
+ readonly "toolbar.groups.file": "File";
925
+ readonly "toolbar.groups.history": "History";
926
+ readonly "toolbar.groups.pages": "Pages";
927
+ readonly "toolbar.groups.other": "More tools";
928
+ readonly "tools.open": "Open a PDF";
929
+ readonly "tools.undo": "Undo";
930
+ readonly "tools.redo": "Redo";
931
+ readonly "tools.rotate-left": "Rotate left";
932
+ readonly "tools.rotate-right": "Rotate right";
729
933
  readonly "errors.UNKNOWN": "Something went wrong. Please try again.";
730
934
  readonly "errors.ABORTED": "The operation was cancelled.";
731
935
  readonly "errors.TIMEOUT": "The operation took too long and was stopped.";
@@ -813,6 +1017,47 @@ export declare interface PdfPlan {
813
1017
  readonly formValues: Readonly<Record<string, Readonly<Record<string, PdfFieldValue>>>>;
814
1018
  }
815
1019
 
1020
+ /**
1021
+ * The plan as portable JSON: `hm-pdf-plan` version 1, which
1022
+ * `formats/hm-pdf-plan/v1.schema.json` describes
1023
+ * (docs/formats/hm-pdf-plan.md). Positions and sizes are whole millionths of
1024
+ * the page, and pages name their sources by ids the document lists.
1025
+ *
1026
+ * @public
1027
+ */
1028
+ export declare interface PdfPlanDocument {
1029
+ readonly format: typeof PDF_PLAN_FORMAT;
1030
+ readonly version: typeof PDF_PLAN_VERSION;
1031
+ readonly sources: Readonly<Record<string, PdfPlanDocumentSource>>;
1032
+ readonly pages: readonly PdfPlanDocumentPage[];
1033
+ readonly formValues: Readonly<Record<string, Readonly<Record<string, PdfFieldValue>>>>;
1034
+ }
1035
+
1036
+ /**
1037
+ * A page in a plan document.
1038
+ *
1039
+ * @public
1040
+ */
1041
+ export declare interface PdfPlanDocumentPage {
1042
+ readonly key: string;
1043
+ readonly source: string;
1044
+ readonly pageIndex: number;
1045
+ readonly rotation: PdfRotation;
1046
+ readonly annotations: readonly PdfAnnotationDocument[];
1047
+ }
1048
+
1049
+ /**
1050
+ * A source, as a plan document records it: its page count, which the pages
1051
+ * that use it must fit, and, once documents travel with their files, its
1052
+ * content.
1053
+ *
1054
+ * @public
1055
+ */
1056
+ export declare interface PdfPlanDocumentSource {
1057
+ readonly pageCount: number;
1058
+ readonly asset?: PdfAssetReference;
1059
+ }
1060
+
816
1061
  /**
817
1062
  * One page of the page plan (docs/adr/0003): a page of a source document,
818
1063
  * with a rotation added to its own, and the annotations drawn on it. The key
@@ -968,7 +1213,10 @@ export declare interface PdfRotatePagesCommand {
968
1213
  readonly type: "pdf.rotatePages";
969
1214
  /** The keys of the pages to rotate. */
970
1215
  readonly pages: readonly string[];
971
- /** Degrees, clockwise, in multiples of 90. Negative turns anticlockwise. */
1216
+ /**
1217
+ * Degrees, clockwise, in multiples of 90 from -360 to 360. Negative turns
1218
+ * anticlockwise.
1219
+ */
972
1220
  readonly angle: number;
973
1221
  }
974
1222
 
@@ -1009,9 +1257,11 @@ export declare interface PdfSession {
1009
1257
  */
1010
1258
  insert(file: Blob | PdfBytes, options?: PdfInsertOptions): Promise<void>;
1011
1259
  /**
1012
- * Runs one command, or several as one undoable step. Throws `TypeError`
1013
- * or `RangeError` for a command that doesn't fit the plan, and changes
1014
- * nothing then.
1260
+ * Runs one command, or several as one undoable step. Throws `PdfError`
1261
+ * with `INVALID_COMMAND` for a command that doesn't fit the plan, with a
1262
+ * `PdfCommandRejection` as `details.reason`, and changes nothing then.
1263
+ * Positions and sizes are snapped to millionths of the page
1264
+ * (`PDF_POSITION_GRID`).
1015
1265
  */
1016
1266
  execute(commands: PdfCommand | readonly PdfCommand[]): void;
1017
1267
  undo(): void;
@@ -1199,6 +1449,20 @@ export declare interface PdfStrokeAnnotation {
1199
1449
  readonly width: number;
1200
1450
  }
1201
1451
 
1452
+ /**
1453
+ * A pen or highlighter stroke in a plan document. Its points and width are
1454
+ * whole millionths of the page.
1455
+ *
1456
+ * @public
1457
+ */
1458
+ export declare interface PdfStrokeAnnotationDocument {
1459
+ readonly id: string;
1460
+ readonly type: "pen" | "highlight";
1461
+ readonly points: readonly PdfDocumentPoint[];
1462
+ readonly color: PdfColor;
1463
+ readonly width: number;
1464
+ }
1465
+
1202
1466
  /**
1203
1467
  * A text note placed on the page.
1204
1468
  *
@@ -1216,6 +1480,21 @@ export declare interface PdfTextAnnotation {
1216
1480
  readonly color: PdfColor;
1217
1481
  }
1218
1482
 
1483
+ /**
1484
+ * A text note in a plan document. Its position and size are whole
1485
+ * millionths of the page.
1486
+ *
1487
+ * @public
1488
+ */
1489
+ export declare interface PdfTextAnnotationDocument {
1490
+ readonly id: string;
1491
+ readonly type: "text";
1492
+ readonly at: PdfDocumentPoint;
1493
+ readonly text: string;
1494
+ readonly size: number;
1495
+ readonly color: PdfColor;
1496
+ }
1497
+
1219
1498
  /**
1220
1499
  * The text of one page, in reading order as the document stores it.
1221
1500
  *
@@ -1269,6 +1548,40 @@ export declare interface PdfWarning {
1269
1548
  readonly actual: number;
1270
1549
  }
1271
1550
 
1551
+ /**
1552
+ * Reads a command in its portable form, `hm-pdf-command` version 1, such as
1553
+ * one parsed from JSON, into the command the session executes: an
1554
+ * annotation's millionths become fractions of the page. The session's
1555
+ * reducer checks everything else when the command runs.
1556
+ *
1557
+ * @param value - The parsed JSON.
1558
+ * @throws `PdfError` with `INVALID_COMMAND` and `malformed-command` for a
1559
+ * position or size that isn't whole millionths, and `unknown-command` for
1560
+ * `pdf.restorePages`, which isn't part of the format.
1561
+ * @public
1562
+ */
1563
+ export declare function readPdfCommandDocument(value: unknown): PdfCommand;
1564
+
1565
+ /**
1566
+ * Reads a plan document, such as one parsed from JSON, checking it as
1567
+ * {@link PdfPlanDocument}'s schema does and more: every page's source must
1568
+ * be one the document lists, with the page's index, and page keys and each
1569
+ * page's annotation ids must be unique. Unknown fields are refused, never
1570
+ * dropped.
1571
+ *
1572
+ * @param value - The parsed JSON.
1573
+ * @returns The plan, with positions as fractions of the page, and its
1574
+ * sources by id.
1575
+ * @throws `PdfError` with `UNSUPPORTED_FORMAT` for another format or a later
1576
+ * version, and `INVALID_DOCUMENT` for anything else that's wrong, with a
1577
+ * {@link PdfDocumentRejection} as `details.reason`.
1578
+ * @public
1579
+ */
1580
+ export declare function readPdfPlanDocument(value: unknown): {
1581
+ readonly plan: PdfPlan;
1582
+ readonly sources: Readonly<Record<string, PdfPlanDocumentSource>>;
1583
+ };
1584
+
1272
1585
  /**
1273
1586
  * The URL, normalised, if it's an absolute `http`, `https` or `mailto` URL
1274
1587
  * without credentials (ADR 0012), and otherwise undefined. Every engine
@@ -1283,4 +1596,29 @@ export declare interface PdfWarning {
1283
1596
  */
1284
1597
  export declare function safeLinkUrl(url: string): string | undefined;
1285
1598
 
1599
+ /**
1600
+ * Writes a command in its portable form, `hm-pdf-command` version 1, with an
1601
+ * annotation's positions and sizes in whole millionths of the page.
1602
+ *
1603
+ * @param command - A command the session applied, so its values are on the
1604
+ * grid.
1605
+ * @throws `TypeError` for `pdf.restorePages`, which isn't part of the
1606
+ * format, and for a signature annotation, which version 1 can't hold.
1607
+ * @public
1608
+ */
1609
+ export declare function toPdfCommandDocument(command: PdfCommand): PdfCommandDocument;
1610
+
1611
+ /**
1612
+ * Writes a plan as a {@link PdfPlanDocument}, plain JSON-ready data, with
1613
+ * positions and sizes in whole millionths of the page.
1614
+ *
1615
+ * @param plan - The plan, such as a session snapshot's.
1616
+ * @param sources - The sources by id, with at least every one the plan's
1617
+ * pages and form values use. They're written as given.
1618
+ * @throws `TypeError` if a source the plan uses is missing from `sources`,
1619
+ * or the plan has a signature annotation, which version 1 can't hold.
1620
+ * @public
1621
+ */
1622
+ export declare function toPdfPlanDocument(plan: PdfPlan, sources: Readonly<Record<string, PdfPlanDocumentSource>>): PdfPlanDocument;
1623
+
1286
1624
  export { }