@hussmartinez/pdf-sdk 0.2.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/README.md +8 -4
- package/dist/assets/processing/processing.worker.js +1 -1
- package/dist/index.d.ts +326 -6
- package/dist/index.js +233 -1
- package/dist/index.js.map +1 -0
- package/dist/lazy/{processing-worker-DU8GEYFs.js → processing-worker-Dy5JQHXJ.js} +2 -2
- package/dist/lazy/{processing-worker-DU8GEYFs.js.map → processing-worker-Dy5JQHXJ.js.map} +1 -1
- package/dist/react.d.ts +29 -6
- package/dist/react.js +11 -39
- package/dist/react.js.map +1 -1
- package/dist/shared/{en-BYB_GHqG.js → en-CQX26xju.js} +339 -175
- package/dist/shared/en-CQX26xju.js.map +1 -0
- package/formats/hm-pdf-command/v1.schema.json +162 -0
- package/formats/hm-pdf-plan/v1.schema.json +259 -0
- package/package.json +10 -5
- package/dist/shared/en-BYB_GHqG.js.map +0 -1
package/README.md
CHANGED
|
@@ -55,6 +55,10 @@ Choose which tools are present with `tools`, and arrange the toolbar with `toolb
|
|
|
55
55
|
|
|
56
56
|
Shortcuts work only while focus is inside the editor, never on the rest of your page, and never while typing in a field. The toolbar is one tab stop, with arrow keys between its buttons; each button names its shortcut in `aria-keyshortcuts`. Undoing, redoing and rotating are announced to screen readers.
|
|
57
57
|
|
|
58
|
+
## Saving a project
|
|
59
|
+
|
|
60
|
+
`toPdfPlanDocument(plan, sources)` writes the session's plan as portable JSON, `hm-pdf-plan` version 1: the pages in order, their rotations and annotations, and form values, with each source's page count. It holds no PDF bytes and no file names, so store the source files alongside it. `readPdfPlanDocument(json)` reads one back, refusing another format or a later version with `UNSUPPORTED_FORMAT`, and anything invalid with `INVALID_DOCUMENT`, each with a stable `details.reason`. The JSON Schemas ship with the package, under `@hussmartinez/pdf-sdk/formats/`, for validating documents elsewhere, such as on a server. [The format record](docs/formats/hm-pdf-plan.md) describes the format, how to load its schemas, and its conformance vectors ([sdk-core ADR 0045](https://github.com/ie-huss-martinez/sdk-core/blob/main/docs/adr/0045-portable-formats-and-conformance-vectors.md)).
|
|
61
|
+
|
|
58
62
|
## Assets and Content Security Policy
|
|
59
63
|
|
|
60
64
|
The SDK runs two workers: pdf.js's, which renders, and one with qpdf and pdf-lib, which builds documents. Some documents also need extra data: CMaps for CJK text whose fonts aren't embedded, standard fonts, and decoders for JBIG2 and JPX images, which are common in scanned documents. The SDK never fetches any of them from another origin. Choose one of two modes ([ADR 0002](docs/adr/0002-workers-and-assets.md), [ADR 0006](docs/adr/0006-icc-colour-and-self-hosted-assets.md), [ADR 0007](docs/adr/0007-one-assets-directory.md)):
|
|
@@ -72,7 +76,7 @@ The SDK runs two workers: pdf.js's, which renders, and one with qpdf and pdf-lib
|
|
|
72
76
|
|
|
73
77
|
**In self-hosted mode, copy the whole directory again whenever you upgrade the package.** A worker left over from another version is refused with `WORKER_START_FAILED`, whose `details` name the file and both versions, `{ asset, expected, actual }`: the processing worker checks the package's version, pdf.js checks its own, and the processing worker also refuses a `qpdf.wasm` from another version.
|
|
74
78
|
|
|
75
|
-
`assetsUrl` can be absolute or relative to the page, such as `/pdf-sdk/`.
|
|
79
|
+
`assetsUrl` can be absolute or relative to the page, such as `/pdf-sdk/`. A relative one is resolved when a worker first starts, in the browser, so `PdfEditor`, `PdfSessionProvider`, `createPdfJsEngine` and `createPdfProcessor` all accept it on a server. A URL with a query or a fragment is refused, because the files resolved from it would lose them: the components throw `TypeError` as they render, and `createPdfJsEngine` and `createPdfProcessor` throw it when you call them.
|
|
76
80
|
|
|
77
81
|
## Development
|
|
78
82
|
|
|
@@ -88,7 +92,7 @@ pnpm verify:fast # the subset the pre-push hook runs
|
|
|
88
92
|
|
|
89
93
|
The examples use the built package as an application would: [`examples/next`](examples/next) renders the editor in a Next.js App Router Server Component, and [`examples/vite`](examples/vite) has one page per asset mode, each under the Content Security Policy this README gives for it. The plain HTML example joins them with the standalone script.
|
|
90
94
|
|
|
91
|
-
|
|
95
|
+
The browser and end-to-end tests also need Docker. They run in the pinned browser test image from [`ci/Dockerfile`](ci/Dockerfile), as in CI, through `hm-in-image` from `@hussmartinez/sdk-config` ([sdk-core ADR 0049](https://github.com/ie-huss-martinez/sdk-core/blob/main/docs/adr/0049-local-browser-tests-in-the-pinned-image.md)). The first run builds the image and installs the dependencies into its volumes. `pnpm test:browser:all` runs all three engines, as CI does.
|
|
92
96
|
|
|
93
97
|
`pnpm verify` runs, in order:
|
|
94
98
|
|
|
@@ -100,9 +104,9 @@ Browser tests need Playwright's browsers once: `pnpm exec playwright install chr
|
|
|
100
104
|
| Dependency rules | `lint:deps` | dependency-cruiser, through `hm-lint-deps` |
|
|
101
105
|
| Build | `build` | Vite, then api-extractor for the type declarations |
|
|
102
106
|
| Unit tests | `test` | Vitest |
|
|
103
|
-
| Browser tests | `test:browser` | Vitest in Chromium, and in Firefox and WebKit too in CI |
|
|
107
|
+
| Browser tests | `test:browser` | Vitest in Chromium in the browser test image, and in Firefox and WebKit too in CI |
|
|
104
108
|
| Examples | `build:examples` | Production builds of the Next.js and Vite examples, against the built package |
|
|
105
|
-
| End-to-end tests | `test:e2e` | Playwright against the examples: server rendering and hydration, axe, no foreign requests, and both asset modes under the Content Security Policies above |
|
|
109
|
+
| End-to-end tests | `test:e2e` | Playwright in the browser test image, against the examples: server rendering and hydration, axe, no foreign requests, and both asset modes under the Content Security Policies above |
|
|
106
110
|
| Size budgets | `check:size` | size-limit, brotli size of each entry point |
|
|
107
111
|
| API reports | `check:api` | api-extractor, one report per entry point in [`api`](api), and `hm-check-api-reports` across them |
|
|
108
112
|
| Package checks | `check:package` | publint and Are the Types Wrong? |
|
|
@@ -54,4 +54,4 @@ end\
|
|
|
54
54
|
endstream
|
|
55
55
|
endobj
|
|
56
56
|
`))}finish(e){let t=this.offsets.size+1,n=this.length,r=`xref\n0 ${t}\n0000000000 65535 f \n`,i=[...this.offsets.entries()].sort(([e],[t])=>e-t);for(let[,e]of i)r+=`${String(e).padStart(10,`0`)} 00000 n \n`;r+=`trailer\n<< /Size ${t} /Root ${e} 0 R >>\nstartxref\n${n}\n%%EOF\n`,this.push(ev(r));let a=new Uint8Array(this.length),o=0;for(let e of this.chunks)a.set(e,o),o+=e.length;return a}push(e){this.chunks.push(e),this.length+=e.length}}})),iv=/* @__PURE__ */ c({PdfError:()=>Y_,PdfPasswordError:()=>X_,PdfToolkit:()=>mv,createPdfToolkit:()=>av,imagesToPdf:()=>Q_});function av(e={}){return mv.create(e)}function ov(e){return typeof e==`object`&&e&&`data`in e?e:{data:e}}function sv(e){return e.replace(/[^\w.-]/g,`_`)||`attachment`}function cv(e){return Number.parseInt(e.replace(/^part-/,``),10)}function lv(e){return`--password=${e}`}function uv(e){return typeof e==`number`?String(e):typeof e==`string`?e:e.map(String).join(`,`)}function dv(e){let{userPassword:t,ownerPassword:n=t,keyLength:r=256,permissions:i={}}=e,a=[];r===40&&a.push(`--allow-weak-crypto`),a.push(`--encrypt`,`--user-password=${t}`,`--owner-password=${n}`,`--bits=${r}`),r===128&&a.push(`--use-aes=y`);let{print:o,modify:s,extract:c,accessibility:l}=i;return r===40?(o!==void 0&&a.push(`--print=${o===`none`?`n`:`y`}`),s!==void 0&&a.push(`--modify=${s===`none`?`n`:`y`}`),c!==void 0&&a.push(`--extract=${c?`y`:`n`}`)):(o!==void 0&&a.push(`--print=${o}`),s!==void 0&&a.push(`--modify=${s}`),c!==void 0&&a.push(`--extract=${c?`y`:`n`}`),l!==void 0&&a.push(`--accessibility=${l?`y`:`n`}`)),a.push(`--`),a}function fv(e){if(e.exitCode!==0&&e.exitCode!==3)throw pv(e)}function pv(e){let t=e.stderr.trim(),n=t.split(`
|
|
57
|
-
`).at(-1)??`qpdf failed with exit code ${e.exitCode}`;return/invalid password|password.*(required|incorrect)/i.test(t)?new X_(n,e.exitCode,t):new Y_(n,e.exitCode,t)}var mv,hv=o((()=>{J_(),Z_(),rv(),mv=class e{runner;constructor(e){this.runner=e}static async create(t={}){return new e(await G_.create(t))}unlock(e,t){return this.transform(e,[lv(t.password),`--decrypt`])}removePassword(e,t){return this.unlock(e,t)}lock(e,t){return this.transform(e,dv(t))}changePassword(e,t){let n={userPassword:t.newPassword,ownerPassword:t.newOwnerPassword??t.newPassword,...t.keyLength!==void 0&&{keyLength:t.keyLength},...t.permissions!==void 0&&{permissions:t.permissions}};return this.transform(e,[lv(t.currentPassword),...dv(n)])}async merge(e){if(e.length===0)throw TypeError(`merge() needs at least one source document`);let t=e.map(ov);return this.runner.run(t.map(e=>e.data),({dir:e,inputPaths:n,exec:r,fs:i})=>{let a=[`--empty`,`--pages`];t.forEach((e,t)=>{a.push(n[t]),e.password!==void 0&&a.push(`--password=${e.password}`),a.push(e.pages===void 0?`1-z`:uv(e.pages))});let o=`${e}/out.pdf`;return a.push(`--`,o),fv(r(a)),i.readFile(o)})}async split(e,t={}){let n=t.pagesPerFile??1;if(!Number.isInteger(n)||n<1)throw TypeError(`pagesPerFile must be a positive integer, got ${n}`);return this.runner.run([e],({dir:e,inputPaths:r,exec:i,fs:a})=>{let o=[];return t.password!==void 0&&o.push(lv(t.password)),o.push(`--split-pages=${n}`,r[0],`${e}/part-%d.pdf`),fv(i(o)),a.readdir(e).filter(e=>e.startsWith(`part-`)).sort((e,t)=>cv(e)-cv(t)).map(t=>a.readFile(`${e}/${t}`))})}extractPages(e,t){let n=[];return t.password!==void 0&&n.push(lv(t.password)),n.push(`--pages`,`.`,uv(t.pages),`--`),this.transform(e,n)}async rotate(e,t){let{angle:n,absolute:r=!1,pages:i,password:a}=t;if(r&&n<0)throw TypeError(`absolute rotation must use a non-negative angle (90, 180, or 270)`);let o=`${r?``:n<0?`-`:`+`}${Math.abs(n)}${i===void 0?``:`:${uv(i)}`}`,s=[];return a!==void 0&&s.push(lv(a)),s.push(`--rotate=${o}`),this.transform(e,s)}async pageCount(e,t={}){return this.runner.run([e],({inputPaths:e,exec:n})=>{let r=[];t.password!==void 0&&r.push(lv(t.password)),r.push(`--show-npages`,e[0]);let i=n(r);return fv(i),Number.parseInt(i.stdoutText.trim(),10)})}async isEncrypted(e){return this.runner.run([e],({inputPaths:e,exec:t})=>{let n=t([`--is-encrypted`,e[0]]);if(n.exitCode===0)return!0;if(n.exitCode===2)return!1;throw pv(n)})}async requiresPassword(e){return this.runner.run([e],({inputPaths:e,exec:t})=>{let n=t([`--requires-password`,e[0]]);if(n.exitCode===0)return!0;if(n.exitCode===2||n.exitCode===3)return!1;throw pv(n)})}compress(e,t={}){let{password:n,compressionLevel:r=9,objectStreams:i=!0,linearize:a=!1}=t;if(!Number.isInteger(r)||r<1||r>9)throw TypeError(`compressionLevel must be 1-9, got ${r}`);let o=[];return n!==void 0&&o.push(lv(n)),o.push(`--compress-streams=y`,`--recompress-flate`,`--compression-level=${r}`,`--object-streams=${i?`generate`:`preserve`}`),a&&o.push(`--linearize`),this.transform(e,o)}linearize(e,t={}){let n=[];return t.password!==void 0&&n.push(lv(t.password)),n.push(`--linearize`),this.transform(e,n)}repair(e,t={}){let n=[];return t.password!==void 0&&n.push(lv(t.password)),this.transform(e,n)}async watermark(e,t,n={}){let{mode:r=`overlay`,password:i,stampPassword:a,to:o,from:s,repeat:c}=n;return this.runner.run([e,t],({dir:e,inputPaths:t,exec:n,fs:l})=>{let u=[];i!==void 0&&u.push(lv(i)),u.push(`--${r}`,t[1]),a!==void 0&&u.push(`--password=${a}`),o!==void 0&&u.push(`--to=${uv(o)}`),s!==void 0&&u.push(`--from=${uv(s)}`),c!==void 0&&u.push(`--repeat=${uv(c)}`);let d=`${e}/out.pdf`;return u.push(`--`,t[0],d),fv(n(u)),l.readFile(d)})}deletePages(e,t){let n={pages:`1-z,${uv(t.pages).split(`,`).map(e=>`x${e}`).join(`,`)}`,...t.password!==void 0&&{password:t.password}};return this.extractPages(e,n)}reversePages(e,t={}){return this.extractPages(e,{pages:`z-1`,...t})}async collate(e,t={}){let n=t.groupSize??1;if(!Number.isInteger(n)||n<1)throw TypeError(`groupSize must be a positive integer, got ${n}`);if(e.length<2)throw TypeError(`collate() needs at least two source documents`);let r=e.map(ov);return this.runner.run(r.map(e=>e.data),({dir:e,inputPaths:t,exec:i,fs:a})=>{let o=[`--empty`,`--collate=${n}`,`--pages`];r.forEach((e,n)=>{o.push(t[n]),e.password!==void 0&&o.push(`--password=${e.password}`),o.push(e.pages===void 0?`1-z`:uv(e.pages))});let s=`${e}/out.pdf`;return o.push(`--`,s),fv(i(o)),a.readFile(s)})}flatten(e,t={}){let n=[];return t.password!==void 0&&n.push(lv(t.password)),n.push(`--generate-appearances`,`--flatten-annotations=${t.annotations??`all`}`),this.transform(e,n)}async addAttachment(e,t){let{data:n,name:r,mimeType:i,description:a,password:o}=t;return this.runner.run([e],async({dir:e,inputPaths:t,exec:s,fs:c})=>{let l=`${e}/${sv(r)}`;c.writeFile(l,await W_(n));let u=[];o!==void 0&&u.push(lv(o)),u.push(`--add-attachment`,l,`--key=${r}`,`--filename=${r}`),i!==void 0&&u.push(`--mimetype=${i}`),a!==void 0&&u.push(`--description=${a}`);let d=`${e}/out.pdf`;return u.push(`--`,t[0],d),fv(s(u)),c.readFile(d)})}removeAttachment(e,t){let n=[];return t.password!==void 0&&n.push(lv(t.password)),n.push(`--remove-attachment=${t.name}`),this.transform(e,n)}async getAttachment(e,t){return this.runner.run([e],({inputPaths:e,exec:n})=>{let r=[];t.password!==void 0&&r.push(lv(t.password)),r.push(`--show-attachment=${t.name}`,e[0]);let i=n(r);return fv(i),i.stdout})}async listAttachments(e,t={}){return(await this.getInfo(e,t)).attachments}async getInfo(e,t={}){return this.runner.run([e],({inputPaths:e,exec:n,fs:r})=>{let i=n([...t.password===void 0?[]:[lv(t.password)],`--json`,`--json-key=encrypt`,`--json-key=attachments`,`--json-key=pages`,e[0]]);fv(i);let a=JSON.parse(i.stdoutText),o=new TextDecoder(`latin1`).decode(r.readFile(e[0]).slice(0,1024)),s=/%PDF-(\d+\.\d+)/.exec(o)?.[1]??`unknown`,c=Object.entries(a.attachments??{}).map(([e,t])=>({name:e,...t.preferredname!==void 0&&{filename:t.preferredname},...t.description!==void 0&&{description:t.description}})),l=a.encrypt,u={pdfVersion:s,pageCount:a.pages?.length??0,encrypted:l?.encrypted??!1,attachments:c};if(l?.encrypted){let e=l.capabilities??{};u.encryption={bits:l.parameters?.bits??0,method:l.parameters?.method??`unknown`,userPasswordMatched:l.userpasswordmatched??!1,ownerPasswordMatched:l.ownerpasswordmatched??!1,permissions:{accessibility:e.accessibility??!1,extract:e.extract??!1,print:e.printhigh??e.printlow??!1,modify:e.modify??!1,annotate:e.modifyannotations??!1,fillForms:e.modifyforms??!1,assemble:e.modifyassembly??!1}}}return u})}async raw(e,t){return this.runner.run(e,({dir:e,inputPaths:n,exec:r,fs:i})=>{let a=`${e}/out.pdf`;return fv(r(t.map(e=>e.replace(/\$out/g,a).replace(/\$in(\d+)/g,(e,t)=>{let r=n[Number(t)];if(r===void 0)throw TypeError(`no input for placeholder $in${t}`);return r})))),i.readFile(a)})}async transform(e,t){return this.runner.run([e],({dir:e,inputPaths:n,exec:r,fs:i})=>{let a=`${e}/out.pdf`;return fv(r([...t,n[0],a])),i.readFile(a)})}}})),gv;function _v(e){return gv??=(async()=>{let[{createPdfToolkit:t},n]=await Promise.all([Promise.resolve().then(()=>(hv(),iv)),e()]);return t({wasmModule:await WebAssembly.compile(n)})})(),gv.catch(()=>{gv=void 0}),gv}function vv(e){de({async build(t,n){try{return{ok:!0,bytes:await F_(t,{toolkit:()=>_v(e),signal:n.signal,progress:e=>n.progress(e)})}}catch(e){if(e instanceof TypeError||e instanceof RangeError)return{ok:!1,error:e.name,message:e.message};throw e}}},{packageVersion:`0.
|
|
57
|
+
`).at(-1)??`qpdf failed with exit code ${e.exitCode}`;return/invalid password|password.*(required|incorrect)/i.test(t)?new X_(n,e.exitCode,t):new Y_(n,e.exitCode,t)}var mv,hv=o((()=>{J_(),Z_(),rv(),mv=class e{runner;constructor(e){this.runner=e}static async create(t={}){return new e(await G_.create(t))}unlock(e,t){return this.transform(e,[lv(t.password),`--decrypt`])}removePassword(e,t){return this.unlock(e,t)}lock(e,t){return this.transform(e,dv(t))}changePassword(e,t){let n={userPassword:t.newPassword,ownerPassword:t.newOwnerPassword??t.newPassword,...t.keyLength!==void 0&&{keyLength:t.keyLength},...t.permissions!==void 0&&{permissions:t.permissions}};return this.transform(e,[lv(t.currentPassword),...dv(n)])}async merge(e){if(e.length===0)throw TypeError(`merge() needs at least one source document`);let t=e.map(ov);return this.runner.run(t.map(e=>e.data),({dir:e,inputPaths:n,exec:r,fs:i})=>{let a=[`--empty`,`--pages`];t.forEach((e,t)=>{a.push(n[t]),e.password!==void 0&&a.push(`--password=${e.password}`),a.push(e.pages===void 0?`1-z`:uv(e.pages))});let o=`${e}/out.pdf`;return a.push(`--`,o),fv(r(a)),i.readFile(o)})}async split(e,t={}){let n=t.pagesPerFile??1;if(!Number.isInteger(n)||n<1)throw TypeError(`pagesPerFile must be a positive integer, got ${n}`);return this.runner.run([e],({dir:e,inputPaths:r,exec:i,fs:a})=>{let o=[];return t.password!==void 0&&o.push(lv(t.password)),o.push(`--split-pages=${n}`,r[0],`${e}/part-%d.pdf`),fv(i(o)),a.readdir(e).filter(e=>e.startsWith(`part-`)).sort((e,t)=>cv(e)-cv(t)).map(t=>a.readFile(`${e}/${t}`))})}extractPages(e,t){let n=[];return t.password!==void 0&&n.push(lv(t.password)),n.push(`--pages`,`.`,uv(t.pages),`--`),this.transform(e,n)}async rotate(e,t){let{angle:n,absolute:r=!1,pages:i,password:a}=t;if(r&&n<0)throw TypeError(`absolute rotation must use a non-negative angle (90, 180, or 270)`);let o=`${r?``:n<0?`-`:`+`}${Math.abs(n)}${i===void 0?``:`:${uv(i)}`}`,s=[];return a!==void 0&&s.push(lv(a)),s.push(`--rotate=${o}`),this.transform(e,s)}async pageCount(e,t={}){return this.runner.run([e],({inputPaths:e,exec:n})=>{let r=[];t.password!==void 0&&r.push(lv(t.password)),r.push(`--show-npages`,e[0]);let i=n(r);return fv(i),Number.parseInt(i.stdoutText.trim(),10)})}async isEncrypted(e){return this.runner.run([e],({inputPaths:e,exec:t})=>{let n=t([`--is-encrypted`,e[0]]);if(n.exitCode===0)return!0;if(n.exitCode===2)return!1;throw pv(n)})}async requiresPassword(e){return this.runner.run([e],({inputPaths:e,exec:t})=>{let n=t([`--requires-password`,e[0]]);if(n.exitCode===0)return!0;if(n.exitCode===2||n.exitCode===3)return!1;throw pv(n)})}compress(e,t={}){let{password:n,compressionLevel:r=9,objectStreams:i=!0,linearize:a=!1}=t;if(!Number.isInteger(r)||r<1||r>9)throw TypeError(`compressionLevel must be 1-9, got ${r}`);let o=[];return n!==void 0&&o.push(lv(n)),o.push(`--compress-streams=y`,`--recompress-flate`,`--compression-level=${r}`,`--object-streams=${i?`generate`:`preserve`}`),a&&o.push(`--linearize`),this.transform(e,o)}linearize(e,t={}){let n=[];return t.password!==void 0&&n.push(lv(t.password)),n.push(`--linearize`),this.transform(e,n)}repair(e,t={}){let n=[];return t.password!==void 0&&n.push(lv(t.password)),this.transform(e,n)}async watermark(e,t,n={}){let{mode:r=`overlay`,password:i,stampPassword:a,to:o,from:s,repeat:c}=n;return this.runner.run([e,t],({dir:e,inputPaths:t,exec:n,fs:l})=>{let u=[];i!==void 0&&u.push(lv(i)),u.push(`--${r}`,t[1]),a!==void 0&&u.push(`--password=${a}`),o!==void 0&&u.push(`--to=${uv(o)}`),s!==void 0&&u.push(`--from=${uv(s)}`),c!==void 0&&u.push(`--repeat=${uv(c)}`);let d=`${e}/out.pdf`;return u.push(`--`,t[0],d),fv(n(u)),l.readFile(d)})}deletePages(e,t){let n={pages:`1-z,${uv(t.pages).split(`,`).map(e=>`x${e}`).join(`,`)}`,...t.password!==void 0&&{password:t.password}};return this.extractPages(e,n)}reversePages(e,t={}){return this.extractPages(e,{pages:`z-1`,...t})}async collate(e,t={}){let n=t.groupSize??1;if(!Number.isInteger(n)||n<1)throw TypeError(`groupSize must be a positive integer, got ${n}`);if(e.length<2)throw TypeError(`collate() needs at least two source documents`);let r=e.map(ov);return this.runner.run(r.map(e=>e.data),({dir:e,inputPaths:t,exec:i,fs:a})=>{let o=[`--empty`,`--collate=${n}`,`--pages`];r.forEach((e,n)=>{o.push(t[n]),e.password!==void 0&&o.push(`--password=${e.password}`),o.push(e.pages===void 0?`1-z`:uv(e.pages))});let s=`${e}/out.pdf`;return o.push(`--`,s),fv(i(o)),a.readFile(s)})}flatten(e,t={}){let n=[];return t.password!==void 0&&n.push(lv(t.password)),n.push(`--generate-appearances`,`--flatten-annotations=${t.annotations??`all`}`),this.transform(e,n)}async addAttachment(e,t){let{data:n,name:r,mimeType:i,description:a,password:o}=t;return this.runner.run([e],async({dir:e,inputPaths:t,exec:s,fs:c})=>{let l=`${e}/${sv(r)}`;c.writeFile(l,await W_(n));let u=[];o!==void 0&&u.push(lv(o)),u.push(`--add-attachment`,l,`--key=${r}`,`--filename=${r}`),i!==void 0&&u.push(`--mimetype=${i}`),a!==void 0&&u.push(`--description=${a}`);let d=`${e}/out.pdf`;return u.push(`--`,t[0],d),fv(s(u)),c.readFile(d)})}removeAttachment(e,t){let n=[];return t.password!==void 0&&n.push(lv(t.password)),n.push(`--remove-attachment=${t.name}`),this.transform(e,n)}async getAttachment(e,t){return this.runner.run([e],({inputPaths:e,exec:n})=>{let r=[];t.password!==void 0&&r.push(lv(t.password)),r.push(`--show-attachment=${t.name}`,e[0]);let i=n(r);return fv(i),i.stdout})}async listAttachments(e,t={}){return(await this.getInfo(e,t)).attachments}async getInfo(e,t={}){return this.runner.run([e],({inputPaths:e,exec:n,fs:r})=>{let i=n([...t.password===void 0?[]:[lv(t.password)],`--json`,`--json-key=encrypt`,`--json-key=attachments`,`--json-key=pages`,e[0]]);fv(i);let a=JSON.parse(i.stdoutText),o=new TextDecoder(`latin1`).decode(r.readFile(e[0]).slice(0,1024)),s=/%PDF-(\d+\.\d+)/.exec(o)?.[1]??`unknown`,c=Object.entries(a.attachments??{}).map(([e,t])=>({name:e,...t.preferredname!==void 0&&{filename:t.preferredname},...t.description!==void 0&&{description:t.description}})),l=a.encrypt,u={pdfVersion:s,pageCount:a.pages?.length??0,encrypted:l?.encrypted??!1,attachments:c};if(l?.encrypted){let e=l.capabilities??{};u.encryption={bits:l.parameters?.bits??0,method:l.parameters?.method??`unknown`,userPasswordMatched:l.userpasswordmatched??!1,ownerPasswordMatched:l.ownerpasswordmatched??!1,permissions:{accessibility:e.accessibility??!1,extract:e.extract??!1,print:e.printhigh??e.printlow??!1,modify:e.modify??!1,annotate:e.modifyannotations??!1,fillForms:e.modifyforms??!1,assemble:e.modifyassembly??!1}}}return u})}async raw(e,t){return this.runner.run(e,({dir:e,inputPaths:n,exec:r,fs:i})=>{let a=`${e}/out.pdf`;return fv(r(t.map(e=>e.replace(/\$out/g,a).replace(/\$in(\d+)/g,(e,t)=>{let r=n[Number(t)];if(r===void 0)throw TypeError(`no input for placeholder $in${t}`);return r})))),i.readFile(a)})}async transform(e,t){return this.runner.run([e],({dir:e,inputPaths:n,exec:r,fs:i})=>{let a=`${e}/out.pdf`;return fv(r([...t,n[0],a])),i.readFile(a)})}}})),gv;function _v(e){return gv??=(async()=>{let[{createPdfToolkit:t},n]=await Promise.all([Promise.resolve().then(()=>(hv(),iv)),e()]);return t({wasmModule:await WebAssembly.compile(n)})})(),gv.catch(()=>{gv=void 0}),gv}function vv(e){de({async build(t,n){try{return{ok:!0,bytes:await F_(t,{toolkit:()=>_v(e),signal:n.signal,progress:e=>n.progress(e)})}}catch(e){if(e instanceof TypeError||e instanceof RangeError)return{ok:!1,error:e.name,message:e.message};throw e}}},{packageVersion:`0.3.0`})}async function yv(){let e=new URL(`qpdf.wasm`,self.location.href),t=await fetch(e);if(!t.ok)throw new T_(`WORKER_START_FAILED`,`qpdf.wasm couldn't be loaded from ${e}.`,{details:{asset:`qpdf.wasm`,status:t.status}});let n=new Uint8Array(await t.arrayBuffer()),r=[...new Uint8Array(await crypto.subtle.digest(`SHA-256`,n))].map(e=>e.toString(16).padStart(2,`0`)).join(``);if(r!==`48a6044e2b5abb32295fa1682e26f20338181bb2423b2ab6e8456b7c4a8c9756`)throw new T_(`WORKER_START_FAILED`,`qpdf.wasm doesn't match this version of the SDK. Copy dist/assets again after upgrading.`,{details:{asset:`qpdf.wasm`,expected:d,actual:r}});return n}vv(yv);
|
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
|
} & {
|
|
@@ -831,6 +1017,47 @@ export declare interface PdfPlan {
|
|
|
831
1017
|
readonly formValues: Readonly<Record<string, Readonly<Record<string, PdfFieldValue>>>>;
|
|
832
1018
|
}
|
|
833
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
|
+
|
|
834
1061
|
/**
|
|
835
1062
|
* One page of the page plan (docs/adr/0003): a page of a source document,
|
|
836
1063
|
* with a rotation added to its own, and the annotations drawn on it. The key
|
|
@@ -986,7 +1213,10 @@ export declare interface PdfRotatePagesCommand {
|
|
|
986
1213
|
readonly type: "pdf.rotatePages";
|
|
987
1214
|
/** The keys of the pages to rotate. */
|
|
988
1215
|
readonly pages: readonly string[];
|
|
989
|
-
/**
|
|
1216
|
+
/**
|
|
1217
|
+
* Degrees, clockwise, in multiples of 90 from -360 to 360. Negative turns
|
|
1218
|
+
* anticlockwise.
|
|
1219
|
+
*/
|
|
990
1220
|
readonly angle: number;
|
|
991
1221
|
}
|
|
992
1222
|
|
|
@@ -1027,9 +1257,11 @@ export declare interface PdfSession {
|
|
|
1027
1257
|
*/
|
|
1028
1258
|
insert(file: Blob | PdfBytes, options?: PdfInsertOptions): Promise<void>;
|
|
1029
1259
|
/**
|
|
1030
|
-
* Runs one command, or several as one undoable step. Throws `
|
|
1031
|
-
*
|
|
1032
|
-
* 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`).
|
|
1033
1265
|
*/
|
|
1034
1266
|
execute(commands: PdfCommand | readonly PdfCommand[]): void;
|
|
1035
1267
|
undo(): void;
|
|
@@ -1217,6 +1449,20 @@ export declare interface PdfStrokeAnnotation {
|
|
|
1217
1449
|
readonly width: number;
|
|
1218
1450
|
}
|
|
1219
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
|
+
|
|
1220
1466
|
/**
|
|
1221
1467
|
* A text note placed on the page.
|
|
1222
1468
|
*
|
|
@@ -1234,6 +1480,21 @@ export declare interface PdfTextAnnotation {
|
|
|
1234
1480
|
readonly color: PdfColor;
|
|
1235
1481
|
}
|
|
1236
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
|
+
|
|
1237
1498
|
/**
|
|
1238
1499
|
* The text of one page, in reading order as the document stores it.
|
|
1239
1500
|
*
|
|
@@ -1287,6 +1548,40 @@ export declare interface PdfWarning {
|
|
|
1287
1548
|
readonly actual: number;
|
|
1288
1549
|
}
|
|
1289
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
|
+
|
|
1290
1585
|
/**
|
|
1291
1586
|
* The URL, normalised, if it's an absolute `http`, `https` or `mailto` URL
|
|
1292
1587
|
* without credentials (ADR 0012), and otherwise undefined. Every engine
|
|
@@ -1301,4 +1596,29 @@ export declare interface PdfWarning {
|
|
|
1301
1596
|
*/
|
|
1302
1597
|
export declare function safeLinkUrl(url: string): string | undefined;
|
|
1303
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
|
+
|
|
1304
1624
|
export { }
|