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 +21 -0
- package/README.md +142 -0
- package/dist/index.cjs +563 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +710 -0
- package/dist/index.d.ts +710 -0
- package/dist/index.js +543 -0
- package/dist/index.js.map +1 -0
- package/package.json +59 -0
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
|