filecheck-node 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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Filecheck
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,142 @@
1
+ # filecheck-node
2
+
3
+ Filecheck server SDK for Node.js 18+ — jobs, uploads, webhooks, and the server-side job
4
+ verification your fulfillment path must run before trusting a browser-submitted `jobId`.
5
+
6
+ Zero runtime dependencies (built-in `fetch`). ESM + CJS + full TypeScript types.
7
+
8
+ ## Install
9
+
10
+ ```bash
11
+ npm install filecheck-node
12
+ ```
13
+
14
+ ## Quickstart — verify a job before fulfilling
15
+
16
+ The browser Element gives the customer a `jobId`; never trust it blind. Verify server-side:
17
+
18
+ **Express**
19
+
20
+ ```ts
21
+ import Filecheck from 'filecheck-node';
22
+ const fc = new Filecheck(process.env.FILECHECK_SECRET_KEY);
23
+
24
+ app.post('/checkout', async (req, res) => {
25
+ const { ok, state, reason } = await fc.jobs.verify(req.body.filecheck_job_id, {
26
+ workflowId: 'wf_…',
27
+ });
28
+ if (!ok) return res.status(422).json({ error: `files not accepted (${reason})` });
29
+ // fulfill the order; state is 'ready' or 'partial' (warnings accepted by policy)
30
+ res.json({ ok: true, state });
31
+ });
32
+ ```
33
+
34
+ **Next.js (App Router route handler)**
35
+
36
+ ```ts
37
+ import Filecheck from 'filecheck-node';
38
+ const fc = new Filecheck(process.env.FILECHECK_SECRET_KEY!);
39
+
40
+ export async function POST(request: Request) {
41
+ const { jobId } = await request.json();
42
+ const { ok, reason } = await fc.jobs.verify(jobId, { workflowId: 'wf_…' });
43
+ if (!ok) return Response.json({ error: reason }, { status: 422 });
44
+ return Response.json({ ok: true });
45
+ }
46
+ ```
47
+
48
+ `verify()` is the encoded docs checklist: the job must be **terminal**
49
+ (`status ∈ done|skipped|error`), **proceedable** (the Element's `canProceed` equivalent —
50
+ `ready`/`partial` after applying the job's `onFail` policy), and — when you pass `workflowId` —
51
+ must have run the expected workflow. Options: `policy` (override the resolved onFail),
52
+ `strict` (fail closed on `status: 'error'` jobs).
53
+
54
+ ## Uploading + processing files
55
+
56
+ ```ts
57
+ // Two-leg upload (presign + S3) in one call → fileRef
58
+ const { fileRef } = await fc.uploads.create(buffer, { mimeType: 'application/pdf', fileName: 'a.pdf' });
59
+
60
+ // Validate against PDF/X profiles — waits for the result by default
61
+ const { job } = await fc.jobs.validate({ sources: [{ fileRef, profile: ['1b'] }] });
62
+ console.log(job.results?.validate?.[0]?.compliant);
63
+
64
+ // Preflight + autofix — async by default; wait: true to block until terminal
65
+ const fixed = await fc.jobs.fix({ sources: [{ fileRef, profileId: 'default' }], wait: true });
66
+
67
+ // Canonical job with an explicit step pipeline (note: no workflowId here —
68
+ // workflow-driven jobs are created by the browser Element, not this endpoint)
69
+ const created = await fc.jobs.create({
70
+ sources: [{ url: 'https://cdn.example.com/artwork.pdf', steps: [{ type: 'preflight' }] }],
71
+ webhook: { url: 'https://example.com/webhooks/filecheck' },
72
+ });
73
+ ```
74
+
75
+ ### The `wait` option
76
+
77
+ The raw API inconsistently flips sync/async with `sync: true` (create/preflight/previews/fix —
78
+ async default) and `async: true` (validate/optimize — sync default). The SDK normalizes all six
79
+ behind `{ wait?, waitTimeoutMs? }` with defaults matching each endpoint. When the server's ~27 s
80
+ wait budget expires (HTTP 202), the SDK keeps polling `GET /jobs/{id}` client-side up to
81
+ `waitTimeoutMs` (default 120 s; `0` = server-side wait only). Every submit resolves
82
+ `{ job, pending }`.
83
+
84
+ ## API surface
85
+
86
+ | Method | Endpoint |
87
+ |---|---|
88
+ | `fc.jobs.create(params)` | `POST /jobs` |
89
+ | `fc.jobs.preflight/previews/fix/validate/optimize(params)` | `POST /jobs/…` sugar endpoints |
90
+ | `fc.jobs.retrieve(id)` | `GET /jobs/{id}` |
91
+ | `fc.jobs.retrieveRuns(id)` | `GET /jobs/{id}?expand=runs` (flattened per-file summary + proof/download URLs) |
92
+ | `fc.jobs.list({ limit, nextKey })` / `fc.jobs.iterate()` | `GET /jobs` (+ auto-pagination) |
93
+ | `fc.jobs.del(id)` | `DELETE /jobs/{id}` |
94
+ | `fc.jobs.waitUntilTerminal(id, opts)` | polling helper |
95
+ | `fc.jobs.verify(id, opts)` | fulfillment gate (see above) |
96
+ | `fc.uploads.create(file, opts)` | `POST /uploads` + S3 leg → `{ fileRef }` |
97
+ | `fc.orders.create(orderId, params)` | `POST /orders/{id}` |
98
+ | `fc.workflows/connectors/rules/profiles/optimizePresets.list()/.retrieve(id)` | read-only library |
99
+ | `fc.webhooks.constructEvent(rawBody, sig, secret, opts)` | webhook parsing/verification |
100
+
101
+ Client options: `new Filecheck('sk_…', { baseUrl?, timeoutMs?, maxRetries?, fetch?, transport? })`.
102
+ Secret keys are `sk_…`; passing a publishable `pk_…` key throws immediately with an explanation.
103
+ Keys are never echoed in full — errors mask to `sk_…abc4`.
104
+
105
+ ## Webhooks
106
+
107
+ > **Signing status:** Filecheck's per-job `job.completed` webhooks are delivered **unsigned**
108
+ > today; the signature scheme is not finalized. `constructEvent` is structured so verification
109
+ > becomes the default without breaking changes once it ships. Until then, `{ verify: false }` is
110
+ > the explicit, temporary escape hatch.
111
+
112
+ ```ts
113
+ app.post('/webhooks/filecheck', express.raw({ type: 'application/json' }), (req, res) => {
114
+ const event = fc.webhooks.constructEvent(req.body, req.get('x-filecheck-signature'), null, {
115
+ verify: false, // TEMPORARY until Filecheck ships webhook signing
116
+ });
117
+ if (event.type === 'job.completed') {
118
+ // event.payload: { id, status, outcome, taskIds, tasks[], finalized, … }
119
+ }
120
+ res.sendStatus(200);
121
+ });
122
+ ```
123
+
124
+ Always hand `constructEvent` the **raw** body (`express.raw`, `await request.text()`), never a
125
+ re-parsed object — signature verification depends on the exact bytes.
126
+
127
+ ## Errors & retries
128
+
129
+ Typed errors: `AuthenticationError` (401/403 — including API Gateway's bare
130
+ `{"message":"Forbidden"}` shape), `InvalidRequestError` (400), `NotFoundError` (404),
131
+ `RateLimitError` (429), `APIError` (5xx / non-JSON bodies), `ConnectionError` (network/timeout),
132
+ `WebhookSignatureError`. The API has no machine-readable error codes — branch on error class, not
133
+ message text.
134
+
135
+ Retries: idempotent GETs are retried (default 2×, full-jitter backoff, `Retry-After` honored) on
136
+ 429/502/503/504 and network failures. **POSTs are never auto-retried** — the API has no
137
+ idempotency keys, and a duplicated `POST /jobs` creates and bills a second job. If you need
138
+ create-retry semantics, tag sources with `clientRef`/`metaData` and reconcile via `jobs.list()`.
139
+
140
+ ## License
141
+
142
+ MIT