@c9up/vellum 0.1.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/LICENSE +21 -0
- package/README.md +473 -0
- package/dist/Vellum.d.ts +460 -0
- package/dist/Vellum.d.ts.map +1 -0
- package/dist/Vellum.js +479 -0
- package/dist/Vellum.js.map +1 -0
- package/dist/VellumProvider.d.ts +28 -0
- package/dist/VellumProvider.d.ts.map +1 -0
- package/dist/VellumProvider.js +33 -0
- package/dist/VellumProvider.js.map +1 -0
- package/dist/augmentations.d.ts +22 -0
- package/dist/augmentations.d.ts.map +1 -0
- package/dist/augmentations.js +16 -0
- package/dist/augmentations.js.map +1 -0
- package/dist/config.d.ts +33 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +31 -0
- package/dist/config.js.map +1 -0
- package/dist/configure.d.ts +17 -0
- package/dist/configure.d.ts.map +1 -0
- package/dist/configure.js +78 -0
- package/dist/configure.js.map +1 -0
- package/dist/errors.d.ts +9 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +19 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +44 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +44 -0
- package/dist/index.js.map +1 -0
- package/dist/native/generated.d.ts +255 -0
- package/dist/native/generated.d.ts.map +1 -0
- package/dist/native/generated.js +7 -0
- package/dist/native/generated.js.map +1 -0
- package/dist/native.d.ts +50 -0
- package/dist/native.d.ts.map +1 -0
- package/dist/native.js +194 -0
- package/dist/native.js.map +1 -0
- package/dist/responder.d.ts +29 -0
- package/dist/responder.d.ts.map +1 -0
- package/dist/responder.js +101 -0
- package/dist/responder.js.map +1 -0
- package/dist/services/main.d.ts +15 -0
- package/dist/services/main.d.ts.map +1 -0
- package/dist/services/main.js +39 -0
- package/dist/services/main.js.map +1 -0
- package/dist/signers.d.ts +81 -0
- package/dist/signers.d.ts.map +1 -0
- package/dist/signers.js +98 -0
- package/dist/signers.js.map +1 -0
- package/index.darwin-arm64.node +0 -0
- package/index.darwin-x64.node +0 -0
- package/index.linux-arm64-gnu.node +0 -0
- package/index.linux-x64-gnu.node +0 -0
- package/index.win32-x64-msvc.node +0 -0
- package/package.json +67 -0
- package/scripts/build-napi-types.mjs +69 -0
- package/scripts/copy-napi.mjs +48 -0
- package/scripts/generate-metrics.py +150 -0
- package/scripts/generate-napi-types.mjs +156 -0
- package/src/Vellum.ts +829 -0
- package/src/VellumProvider.ts +51 -0
- package/src/augmentations.ts +25 -0
- package/src/config.ts +47 -0
- package/src/configure.ts +92 -0
- package/src/errors.ts +20 -0
- package/src/index.ts +74 -0
- package/src/native/generated.ts +375 -0
- package/src/native.ts +358 -0
- package/src/responder.ts +116 -0
- package/src/services/main.ts +48 -0
- package/src/signers.ts +149 -0
package/dist/Vellum.d.ts
ADDED
|
@@ -0,0 +1,460 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Vellum — the PDF service.
|
|
3
|
+
*
|
|
4
|
+
* Resolved from the container as `vellum`, or imported directly from
|
|
5
|
+
* `@c9up/vellum/services/main`. Every method is asynchronous: rasterising is
|
|
6
|
+
* real computation, and it runs on the libuv thread pool rather than on the
|
|
7
|
+
* thread serving requests.
|
|
8
|
+
*/
|
|
9
|
+
import type { DocumentInfo, DocumentMetadata, FormField, PageDimensions, RevocationAnswer, SignatureReport } from "./native.js";
|
|
10
|
+
import { type ResponderPolicy } from "./responder.js";
|
|
11
|
+
/** Image encodings a page can be rasterised to. */
|
|
12
|
+
export type ImageFormat = "png" | "jpeg";
|
|
13
|
+
/** Rendering defaults, set in `config/vellum.ts`. */
|
|
14
|
+
export interface VellumConfig {
|
|
15
|
+
/** Default encoding. `"png"` unless set. */
|
|
16
|
+
format?: ImageFormat;
|
|
17
|
+
/** Default multiplier over the page's natural size, 1 being 72 DPI. */
|
|
18
|
+
scale?: number;
|
|
19
|
+
/** Default target width in pixels. Takes precedence over `scale`. */
|
|
20
|
+
width?: number;
|
|
21
|
+
/** Default JPEG quality, 1-100. */
|
|
22
|
+
quality?: number;
|
|
23
|
+
/** Default background: `#rgb`, `#rrggbb`, `#rrggbbaa` or `"transparent"`. */
|
|
24
|
+
background?: string;
|
|
25
|
+
/**
|
|
26
|
+
* The most pixels one page may rasterise to. 50 million by default — room
|
|
27
|
+
* for A4 at 600 DPI, and A3 at 400.
|
|
28
|
+
*
|
|
29
|
+
* A page declares its own size, so without a ceiling a document alone was
|
|
30
|
+
* enough to ask for gigabytes: bounding each side to 65535 still leaves 16
|
|
31
|
+
* GiB of RGBA between two of them. Raise it knowingly when you render
|
|
32
|
+
* something genuinely large.
|
|
33
|
+
*/
|
|
34
|
+
maxPixels?: number;
|
|
35
|
+
/**
|
|
36
|
+
* Fonts to write text with, by the name a caller asks for them by. Values
|
|
37
|
+
* are paths to TrueType or OpenType files.
|
|
38
|
+
*
|
|
39
|
+
* ```ts
|
|
40
|
+
* fonts: { body: app.makePath('resources/fonts/Inter-Regular.ttf') }
|
|
41
|
+
* ```
|
|
42
|
+
*
|
|
43
|
+
* A name declared here is looked up before the standard fonts, so calling
|
|
44
|
+
* one `Helvetica` shadows the standard one — deliberately, since a project
|
|
45
|
+
* that ships its own Helvetica means that one.
|
|
46
|
+
*/
|
|
47
|
+
fonts?: Record<string, string>;
|
|
48
|
+
/**
|
|
49
|
+
* Who may sign a document, by the name a caller asks for.
|
|
50
|
+
*
|
|
51
|
+
* ```ts
|
|
52
|
+
* signers: {
|
|
53
|
+
* internal: myLocalSigner,
|
|
54
|
+
* qualified: myProviderSigner,
|
|
55
|
+
* }
|
|
56
|
+
* ```
|
|
57
|
+
*
|
|
58
|
+
* A key held here and a key held by a certified provider are the same
|
|
59
|
+
* thing to this package, because a signer never sees the document — only
|
|
60
|
+
* the digest of it. Which one signs is therefore a line of configuration.
|
|
61
|
+
*/
|
|
62
|
+
signers?: Record<string, Signer>;
|
|
63
|
+
/**
|
|
64
|
+
* Certificates to trust when checking a signature, DER or PEM.
|
|
65
|
+
*
|
|
66
|
+
* Typically the roots of the authorities your jurisdiction recognises,
|
|
67
|
+
* which supervisory bodies publish as a trusted list. Supplying none is a
|
|
68
|
+
* position too: every signature then comes back untrusted, which is the
|
|
69
|
+
* honest answer rather than a comfortable one.
|
|
70
|
+
*/
|
|
71
|
+
trustedAnchors?: ReadonlyArray<Buffer>;
|
|
72
|
+
/**
|
|
73
|
+
* Which revocation responders may be contacted.
|
|
74
|
+
*
|
|
75
|
+
* The address comes out of the certificate inside the document being
|
|
76
|
+
* checked — from whoever sent it. Left unset, only public hosts over
|
|
77
|
+
* http/https are asked, which is what a real certificate authority is. Set
|
|
78
|
+
* it to a list of hostnames, or a predicate, when your authority answers
|
|
79
|
+
* somewhere those rules exclude.
|
|
80
|
+
*/
|
|
81
|
+
allowedResponders?: ResponderPolicy;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Whatever turns a digest into a signature.
|
|
85
|
+
*
|
|
86
|
+
* It is given the SHA-256 of the byte range the signature covers, and returns
|
|
87
|
+
* the CMS `SignedData` to put in the document. It is never given the document:
|
|
88
|
+
* a PDF signature covers a byte range of the file it lives in, so the value
|
|
89
|
+
* has to be computed over a digest and dropped into space reserved for it.
|
|
90
|
+
*
|
|
91
|
+
* That is what lets a key in a file and a certified provider's API be the same
|
|
92
|
+
* interface — and why signing over the network belongs here rather than in the
|
|
93
|
+
* engine, which does no I/O.
|
|
94
|
+
*/
|
|
95
|
+
export interface Signer {
|
|
96
|
+
sign(digest: Buffer): Promise<Buffer>;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* A signature report, plus what the issuer said about the certificate when
|
|
100
|
+
* `checkRevocation` asked.
|
|
101
|
+
*/
|
|
102
|
+
export type CheckedSignature = SignatureReport & {
|
|
103
|
+
revocation?: RevocationAnswer;
|
|
104
|
+
};
|
|
105
|
+
/** What to check a signature against. */
|
|
106
|
+
export interface VerifyOptions {
|
|
107
|
+
/**
|
|
108
|
+
* Certificates to trust as roots, DER or PEM. Falls back to
|
|
109
|
+
* `trustedAnchors` in `config/vellum.ts`.
|
|
110
|
+
*/
|
|
111
|
+
anchors?: ReadonlyArray<Buffer>;
|
|
112
|
+
/** Which responders may be contacted, overriding `config/vellum.ts`. */
|
|
113
|
+
allowedResponders?: ResponderPolicy;
|
|
114
|
+
/**
|
|
115
|
+
* Ask each certificate's issuer whether it still stands.
|
|
116
|
+
*
|
|
117
|
+
* A network call per signature, to the responder the certificate names.
|
|
118
|
+
* The answer has **three** values, not two: `"good"`, `"revoked"`, and
|
|
119
|
+
* `"unknown"` for everything else — the responder was unreachable,
|
|
120
|
+
* answered about something else, or could not be believed. Treating
|
|
121
|
+
* `"unknown"` as good waves through a withdrawn certificate; treating it
|
|
122
|
+
* as revoked rejects documents whenever a server is down. Which to do is
|
|
123
|
+
* your policy, so it is reported rather than decided.
|
|
124
|
+
*/
|
|
125
|
+
checkRevocation?: boolean;
|
|
126
|
+
/** How long to wait on a responder. Default 10 seconds. */
|
|
127
|
+
revocationTimeoutMs?: number;
|
|
128
|
+
}
|
|
129
|
+
/** What the signature says about itself. */
|
|
130
|
+
export interface SignOptions {
|
|
131
|
+
/** Which signer, by the name it has in `config/vellum.ts`. */
|
|
132
|
+
signer: string;
|
|
133
|
+
/** Why the document was signed. */
|
|
134
|
+
reason?: string;
|
|
135
|
+
/** Where it was signed. */
|
|
136
|
+
location?: string;
|
|
137
|
+
/** How to reach the signatory. */
|
|
138
|
+
contact?: string;
|
|
139
|
+
/** Who signed, as it should be displayed. */
|
|
140
|
+
name?: string;
|
|
141
|
+
/** When. Defaults to now. */
|
|
142
|
+
signedAt?: Date;
|
|
143
|
+
/**
|
|
144
|
+
* Bytes reserved for the signature value. Default 16384, comfortable for a
|
|
145
|
+
* timestamped signature. The room cannot be found afterwards, so a signer
|
|
146
|
+
* that returns more than fits has to be given more here.
|
|
147
|
+
*/
|
|
148
|
+
capacity?: number;
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* One of the 14 fonts every PDF reader is required to have.
|
|
152
|
+
*
|
|
153
|
+
* They can be referenced without being embedded, which is why writing text
|
|
154
|
+
* adds nothing to the file and needs no font to be supplied.
|
|
155
|
+
*/
|
|
156
|
+
export type StandardFont = "Helvetica" | "Helvetica-Bold" | "Helvetica-Oblique" | "Times-Roman" | "Times-Bold" | "Times-Italic" | "Courier" | "Courier-Bold";
|
|
157
|
+
/** Where and how a line of text is written onto a page. */
|
|
158
|
+
export interface TextStampOptions extends PageOptions {
|
|
159
|
+
/** Points from the left edge. Default 0. */
|
|
160
|
+
x?: number;
|
|
161
|
+
/**
|
|
162
|
+
* Points from the top edge, to the text's BASELINE — the line the letters
|
|
163
|
+
* sit on, not the top of their bounding box.
|
|
164
|
+
*/
|
|
165
|
+
y?: number;
|
|
166
|
+
/** Type size in points. Default 12. */
|
|
167
|
+
size?: number;
|
|
168
|
+
/**
|
|
169
|
+
* A font named in `config/vellum.ts`, or one of the 14 standard fonts.
|
|
170
|
+
* Default `"Helvetica"`.
|
|
171
|
+
*/
|
|
172
|
+
font?: StandardFont | (string & {});
|
|
173
|
+
/** `#rgb` or `#rrggbb`. Default black. */
|
|
174
|
+
color?: string;
|
|
175
|
+
/** 0 is invisible, 1 is opaque. */
|
|
176
|
+
opacity?: number;
|
|
177
|
+
}
|
|
178
|
+
/** Where and how an image is laid onto a page. */
|
|
179
|
+
export interface StampOptions extends PageOptions {
|
|
180
|
+
/**
|
|
181
|
+
* Points from the left edge. Default 0.
|
|
182
|
+
*
|
|
183
|
+
* Coordinates count from the TOP-LEFT corner, the way a screen layout is
|
|
184
|
+
* written.
|
|
185
|
+
*/
|
|
186
|
+
x?: number;
|
|
187
|
+
/** Points from the top edge. Default 0. */
|
|
188
|
+
y?: number;
|
|
189
|
+
/** Drawn width in points. With `height` absent, the ratio is kept. */
|
|
190
|
+
width?: number;
|
|
191
|
+
/** Drawn height in points. With `width` absent, the ratio is kept. */
|
|
192
|
+
height?: number;
|
|
193
|
+
/** 0 is invisible, 1 is opaque. A watermark usually wants about 0.15. */
|
|
194
|
+
opacity?: number;
|
|
195
|
+
}
|
|
196
|
+
/** Options that address a single page. */
|
|
197
|
+
export interface PageOptions {
|
|
198
|
+
/**
|
|
199
|
+
* Which page, counting from 1 — the number printed on the page, not an
|
|
200
|
+
* array index.
|
|
201
|
+
*/
|
|
202
|
+
page?: number;
|
|
203
|
+
}
|
|
204
|
+
/** Per-call rendering options. Anything omitted falls back to the config. */
|
|
205
|
+
export interface RenderOptions extends VellumConfig, PageOptions {
|
|
206
|
+
}
|
|
207
|
+
export declare class Vellum {
|
|
208
|
+
#private;
|
|
209
|
+
constructor(config?: VellumConfig);
|
|
210
|
+
/** The configured defaults, as the service resolved them. */
|
|
211
|
+
get config(): Readonly<VellumConfig>;
|
|
212
|
+
/**
|
|
213
|
+
* Rasterise a single page to an image.
|
|
214
|
+
*
|
|
215
|
+
* ```ts
|
|
216
|
+
* const preview = await vellum.render(pdf, { page: 1, width: 1200 })
|
|
217
|
+
* ```
|
|
218
|
+
*/
|
|
219
|
+
render(pdf: Buffer, options?: RenderOptions): Promise<Buffer>;
|
|
220
|
+
/**
|
|
221
|
+
* Rasterise every page, in document order.
|
|
222
|
+
*
|
|
223
|
+
* ```ts
|
|
224
|
+
* const pages = await vellum.renderAll(pdf, { format: 'jpeg' })
|
|
225
|
+
* ```
|
|
226
|
+
*/
|
|
227
|
+
renderAll(pdf: Buffer, options?: RenderOptions): Promise<Buffer[]>;
|
|
228
|
+
/** The natural size of every page, in points, before any scaling. */
|
|
229
|
+
dimensions(pdf: Buffer): Promise<PageDimensions[]>;
|
|
230
|
+
/** How many pages the document has, which format version, and whether it is encrypted. */
|
|
231
|
+
inspect(pdf: Buffer): Promise<DocumentInfo>;
|
|
232
|
+
/**
|
|
233
|
+
* What the document says about itself: title, author, subject, keywords,
|
|
234
|
+
* the applications involved, and the dates.
|
|
235
|
+
*
|
|
236
|
+
* Every field is optional, because a PDF is valid with no `/Info` at all
|
|
237
|
+
* and producers fill in whichever ones they like. Dates come back as ISO
|
|
238
|
+
* 8601 when the producer wrote a conforming one, otherwise as the raw
|
|
239
|
+
* string it did write.
|
|
240
|
+
*/
|
|
241
|
+
metadata(pdf: Buffer): Promise<DocumentMetadata>;
|
|
242
|
+
/**
|
|
243
|
+
* The text of a single page.
|
|
244
|
+
*
|
|
245
|
+
* ```ts
|
|
246
|
+
* const text = await vellum.extractText(pdf, { page: 1 })
|
|
247
|
+
* ```
|
|
248
|
+
*
|
|
249
|
+
* Glyphs come back in the order the page draws them, with a line break
|
|
250
|
+
* where the baseline moves. A scanned document with no text layer yields
|
|
251
|
+
* an empty string rather than an error — it has no text to give.
|
|
252
|
+
*/
|
|
253
|
+
extractText(pdf: Buffer, options?: PageOptions): Promise<string>;
|
|
254
|
+
/** The text of every page, in document order. */
|
|
255
|
+
extractTextAll(pdf: Buffer): Promise<string[]>;
|
|
256
|
+
/**
|
|
257
|
+
* Join documents end to end, in the order given.
|
|
258
|
+
*
|
|
259
|
+
* ```ts
|
|
260
|
+
* const dossier = await vellum.merge([contract, annexe, signature])
|
|
261
|
+
* ```
|
|
262
|
+
*
|
|
263
|
+
* Attributes a page inherits from its parent — size, resources — are
|
|
264
|
+
* materialised onto it first, so a page keeps its own size instead of
|
|
265
|
+
* falling back to Letter.
|
|
266
|
+
*/
|
|
267
|
+
merge(pdfs: ReadonlyArray<Buffer>): Promise<Buffer>;
|
|
268
|
+
/**
|
|
269
|
+
* Keep only the pages listed, counting from 1, in document order.
|
|
270
|
+
*
|
|
271
|
+
* ```ts
|
|
272
|
+
* const extract = await vellum.selectPages(pdf, [1, 3, 4])
|
|
273
|
+
* ```
|
|
274
|
+
*/
|
|
275
|
+
selectPages(pdf: Buffer, pages: ReadonlyArray<number>): Promise<Buffer>;
|
|
276
|
+
/** One single-page document per page, in document order. */
|
|
277
|
+
split(pdf: Buffer): Promise<Buffer[]>;
|
|
278
|
+
/**
|
|
279
|
+
* Rotate pages clockwise by `degrees`, a multiple of 90.
|
|
280
|
+
*
|
|
281
|
+
* ```ts
|
|
282
|
+
* const upright = await vellum.rotate(scan, 90, { pages: [1] })
|
|
283
|
+
* ```
|
|
284
|
+
*
|
|
285
|
+
* The rotation is added to what a page already carries, because a scan can
|
|
286
|
+
* arrive already turned.
|
|
287
|
+
*/
|
|
288
|
+
rotate(pdf: Buffer, degrees: number, options?: {
|
|
289
|
+
pages?: ReadonlyArray<number>;
|
|
290
|
+
}): Promise<Buffer>;
|
|
291
|
+
/**
|
|
292
|
+
* Draw an image onto the document — a signature, a photo, a watermark.
|
|
293
|
+
*
|
|
294
|
+
* ```ts
|
|
295
|
+
* const signed = await vellum.stamp(workOrder, signature, {
|
|
296
|
+
* page: 1, x: 380, y: 690, width: 140,
|
|
297
|
+
* })
|
|
298
|
+
* ```
|
|
299
|
+
*
|
|
300
|
+
* PNG and JPEG are accepted, chosen by signature rather than by file name.
|
|
301
|
+
* Omitting `page` stamps every page, which is what a watermark wants.
|
|
302
|
+
*/
|
|
303
|
+
stamp(pdf: Buffer, image: Buffer, options?: StampOptions): Promise<Buffer>;
|
|
304
|
+
/**
|
|
305
|
+
* Write a line of text onto the document.
|
|
306
|
+
*
|
|
307
|
+
* ```ts
|
|
308
|
+
* const marked = await vellum.stampText(invoice, 'PAYÉ', {
|
|
309
|
+
* page: 1, x: 400, y: 80, size: 24, color: '#c00', opacity: 0.6,
|
|
310
|
+
* })
|
|
311
|
+
* ```
|
|
312
|
+
*
|
|
313
|
+
* `font` names one of the 14 standard fonts by default. A PDF may
|
|
314
|
+
* reference those without embedding them, so nothing is added to the file
|
|
315
|
+
* — at the cost of the WinAnsi character set, outside which text is
|
|
316
|
+
* refused rather than mangled.
|
|
317
|
+
*
|
|
318
|
+
* Naming a font declared in `config/vellum.ts` instead embeds it,
|
|
319
|
+
* subsetted to the characters actually written, and lifts that limit:
|
|
320
|
+
*
|
|
321
|
+
* ```ts
|
|
322
|
+
* // config/vellum.ts
|
|
323
|
+
* fonts: { body: app.makePath('resources/fonts/Inter-Regular.ttf') }
|
|
324
|
+
*
|
|
325
|
+
* await vellum.stampText(pdf, 'Uměl Řehoř', { font: 'body' })
|
|
326
|
+
* ```
|
|
327
|
+
*
|
|
328
|
+
* Naming no page writes on every page, which is what a draft marking
|
|
329
|
+
* wants.
|
|
330
|
+
*/
|
|
331
|
+
stampText(pdf: Buffer, text: string, options?: TextStampOptions): Promise<Buffer>;
|
|
332
|
+
/**
|
|
333
|
+
* The interactive fields of the document's form, in declaration order.
|
|
334
|
+
*
|
|
335
|
+
* ```ts
|
|
336
|
+
* for (const field of await vellum.formFields(mandate)) {
|
|
337
|
+
* console.log(field.name, field.kind, field.value)
|
|
338
|
+
* }
|
|
339
|
+
* ```
|
|
340
|
+
*
|
|
341
|
+
* `name` is the fully qualified name — the one used to fill the field in.
|
|
342
|
+
* For a checkbox or a radio group, `options` lists the states the DOCUMENT
|
|
343
|
+
* accepts: their "on" state is not a fixed name, and writing anything else
|
|
344
|
+
* leaves the control untouched.
|
|
345
|
+
*
|
|
346
|
+
* A document with no form yields an empty list rather than an error.
|
|
347
|
+
*/
|
|
348
|
+
formFields(pdf: Buffer): Promise<FormField[]>;
|
|
349
|
+
/**
|
|
350
|
+
* Fill the named fields of the document's form.
|
|
351
|
+
*
|
|
352
|
+
* ```ts
|
|
353
|
+
* const filled = await vellum.fillForm(mandate, {
|
|
354
|
+
* 'assure.nom': 'Amélie Durand',
|
|
355
|
+
* accepted: 'Yes',
|
|
356
|
+
* country: 'CH',
|
|
357
|
+
* })
|
|
358
|
+
* ```
|
|
359
|
+
*
|
|
360
|
+
* Keys are the fully qualified names {@link Vellum.formFields} reports.
|
|
361
|
+
*
|
|
362
|
+
* Each filled field's **appearance stream is regenerated**. Writing the
|
|
363
|
+
* value alone is not enough: most readers paint a field from its
|
|
364
|
+
* appearance, not from its value, so a document filled without that opens
|
|
365
|
+
* looking empty while holding every answer.
|
|
366
|
+
*
|
|
367
|
+
* A name the form does not have is an error rather than a silent no-op —
|
|
368
|
+
* a filled document missing an answer nobody noticed is worse than a
|
|
369
|
+
* failure. The same goes for a read-only field, a value over the field's
|
|
370
|
+
* maximum length, and a checkbox state the document does not accept.
|
|
371
|
+
*/
|
|
372
|
+
fillForm(pdf: Buffer, values: Record<string, string>): Promise<Buffer>;
|
|
373
|
+
/**
|
|
374
|
+
* Paint the form into the page and remove it.
|
|
375
|
+
*
|
|
376
|
+
* ```ts
|
|
377
|
+
* const signed = await vellum.flattenForm(
|
|
378
|
+
* await vellum.fillForm(mandate, { 'assure.nom': 'Amélie Durand' }),
|
|
379
|
+
* )
|
|
380
|
+
* ```
|
|
381
|
+
*
|
|
382
|
+
* The document keeps its look and loses its fields: every widget's
|
|
383
|
+
* appearance becomes ordinary page content, the widget annotations go, and
|
|
384
|
+
* the form itself is dropped. This is what turns a filled document into
|
|
385
|
+
* one nobody can edit back.
|
|
386
|
+
*
|
|
387
|
+
* Annotations that are not form widgets — links, notes — are left where
|
|
388
|
+
* they are. A field holding a value that ships no appearance to paint is
|
|
389
|
+
* an error: the answer would vanish from a document that still looks
|
|
390
|
+
* complete.
|
|
391
|
+
*/
|
|
392
|
+
flattenForm(pdf: Buffer): Promise<Buffer>;
|
|
393
|
+
/**
|
|
394
|
+
* Sign the document with one of the configured signers.
|
|
395
|
+
*
|
|
396
|
+
* ```ts
|
|
397
|
+
* const signed = await vellum.sign(mandate, {
|
|
398
|
+
* signer: 'qualified',
|
|
399
|
+
* reason: 'Mandat de prévoyance',
|
|
400
|
+
* name: 'Amélie Durand',
|
|
401
|
+
* })
|
|
402
|
+
* ```
|
|
403
|
+
*
|
|
404
|
+
* The signature is appended as an **incremental revision**: the bytes it
|
|
405
|
+
* signs are preserved exactly, and nothing already in the document is
|
|
406
|
+
* rewritten. Rewriting would invalidate any signature already on it and
|
|
407
|
+
* destroy the history a signature exists to establish.
|
|
408
|
+
*
|
|
409
|
+
* The signer is handed the digest of what the signature covers and returns
|
|
410
|
+
* the CMS to embed. It never sees the document, which is what makes a
|
|
411
|
+
* local key and a certified provider interchangeable.
|
|
412
|
+
*
|
|
413
|
+
* A visible signature — a drawn one, an image — is a separate matter:
|
|
414
|
+
* {@link Vellum.stamp} it on first, then sign.
|
|
415
|
+
*/
|
|
416
|
+
sign(pdf: Buffer, options: SignOptions): Promise<Buffer>;
|
|
417
|
+
/**
|
|
418
|
+
* Report on every signature the document carries.
|
|
419
|
+
*
|
|
420
|
+
* ```ts
|
|
421
|
+
* for (const signature of await vellum.verifySignatures(mandate)) {
|
|
422
|
+
* if (!signature.coversWholeDocument) reject('content was added after signing')
|
|
423
|
+
* if (!signature.digestMatches) reject('the document has changed')
|
|
424
|
+
* }
|
|
425
|
+
* ```
|
|
426
|
+
*
|
|
427
|
+
* `coversWholeDocument` is the one that catches the trap everybody meets
|
|
428
|
+
* first: content appended after a signature is not covered by it, and the
|
|
429
|
+
* arithmetic over the covered part still checks out. A document whose
|
|
430
|
+
* second half arrived later is not a signed document.
|
|
431
|
+
*
|
|
432
|
+
* This establishes **integrity and authorship, not trust**. It does not ask
|
|
433
|
+
* whether the certificate comes from an authority you accept, nor whether
|
|
434
|
+
* it has since been revoked: that needs a trust store and a live revocation
|
|
435
|
+
* check, neither of which belongs in a PDF engine.
|
|
436
|
+
*
|
|
437
|
+
* `trusted` says a path was found from the signer's certificate to one of
|
|
438
|
+
* the anchors you accept, judged **at the moment of signing** rather than
|
|
439
|
+
* now — a certificate that has since expired did not retroactively unsign
|
|
440
|
+
* anything. `moment` says where that instant came from: a timestamp is
|
|
441
|
+
* worth having because it makes it something other than the signer's word.
|
|
442
|
+
*
|
|
443
|
+
* **Revocation is not checked** unless `checkRevocation` asks for it. A
|
|
444
|
+
* certificate withdrawn after it was issued otherwise still looks valid
|
|
445
|
+
* here.
|
|
446
|
+
*
|
|
447
|
+
* When it is asked for, the responder's address comes out of the
|
|
448
|
+
* certificate inside the document — from whoever sent it. Only public hosts
|
|
449
|
+
* over http/https are contacted; a document does not get to point your
|
|
450
|
+
* server at your own network. Name your authority in `allowedResponders`
|
|
451
|
+
* when it answers somewhere that rule excludes.
|
|
452
|
+
*
|
|
453
|
+
* A document with no signatures reports none. That is an answer, not a
|
|
454
|
+
* failure.
|
|
455
|
+
*/
|
|
456
|
+
verifySignatures(pdf: Buffer, options?: VerifyOptions): Promise<CheckedSignature[]>;
|
|
457
|
+
/** How many pages the document has. */
|
|
458
|
+
pageCount(pdf: Buffer): Promise<number>;
|
|
459
|
+
}
|
|
460
|
+
//# sourceMappingURL=Vellum.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"Vellum.d.ts","sourceRoot":"","sources":["../src/Vellum.ts"],"names":[],"mappings":"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"}
|