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/dist/index.d.ts
ADDED
|
@@ -0,0 +1,710 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Response types, hand-aligned with the API's response formatter
|
|
3
|
+
* (`filecheck-api/_layers/mixins/nodejs/format.mjs` — formatJob / formatTask
|
|
4
|
+
* / formatStep and the result extractors). Enum values from `steps.mjs`.
|
|
5
|
+
*
|
|
6
|
+
* Lean vs full: creation responses (201/202) and `GET /jobs` list entries
|
|
7
|
+
* are LEAN — no `summary`, no `results`, truncated steps. Only a non-lean
|
|
8
|
+
* detail read (`GET /jobs/{id}`, or a 200 sync submit) carries the full
|
|
9
|
+
* shape. Fields only present on full responses are optional here.
|
|
10
|
+
*/
|
|
11
|
+
type JobStatus = 'pending' | 'running' | 'done' | 'skipped' | 'error';
|
|
12
|
+
/** Task/step outcome; `mixed` additionally appears at the job level. */
|
|
13
|
+
type Outcome = 'pass' | 'warn' | 'fail' | 'fixed' | 'unchanged' | 'na' | 'mixed';
|
|
14
|
+
type OnFailPolicy = 'reject' | 'accept_with_warnings' | 'manual_review';
|
|
15
|
+
type StepType = 'preflight' | 'autofix' | 'repreflight' | 'validate' | 'previews' | 'optimize' | 'convert' | 'upscale' | 'removebg' | 'split_pages' | 'deliver' | 'proof';
|
|
16
|
+
type FileType = 'pdf' | 'raster' | 'vector' | 'office' | 'archive' | 'font' | 'other';
|
|
17
|
+
declare const TERMINAL_STATUSES: ReadonlySet<JobStatus>;
|
|
18
|
+
/** A job (or task) will not transition again once its status is terminal. */
|
|
19
|
+
declare function isTerminal(subject: {
|
|
20
|
+
status: JobStatus;
|
|
21
|
+
}): boolean;
|
|
22
|
+
/** File/report artifact pointer. `downloadUrl` only when the read was signed. */
|
|
23
|
+
interface Artifact {
|
|
24
|
+
role?: string;
|
|
25
|
+
kind?: string;
|
|
26
|
+
taskId?: string;
|
|
27
|
+
bucket?: string | null;
|
|
28
|
+
key?: string | null;
|
|
29
|
+
mimeType?: string | null;
|
|
30
|
+
sizeBytes?: number | null;
|
|
31
|
+
fileName?: string | null;
|
|
32
|
+
/** Presigned GET URL (60-minute TTL) — present on signed detail reads. */
|
|
33
|
+
downloadUrl?: string | null;
|
|
34
|
+
expiresIn?: number | null;
|
|
35
|
+
[key: string]: unknown;
|
|
36
|
+
}
|
|
37
|
+
interface Step {
|
|
38
|
+
id: string;
|
|
39
|
+
type: StepType;
|
|
40
|
+
status: JobStatus;
|
|
41
|
+
outcome: Outcome | null;
|
|
42
|
+
reason: string | null;
|
|
43
|
+
params: Record<string, unknown> | null;
|
|
44
|
+
/** Full (non-lean) responses only. */
|
|
45
|
+
runtimeParams?: Record<string, unknown> | null;
|
|
46
|
+
started?: string | null;
|
|
47
|
+
ended?: string | null;
|
|
48
|
+
duration?: number | null;
|
|
49
|
+
inStream?: string | null;
|
|
50
|
+
outputs?: Array<Record<string, unknown>>;
|
|
51
|
+
}
|
|
52
|
+
interface Task {
|
|
53
|
+
id: string;
|
|
54
|
+
createdAt: string | null;
|
|
55
|
+
updatedAt: string | null;
|
|
56
|
+
status: JobStatus;
|
|
57
|
+
outcome: Outcome | null;
|
|
58
|
+
fileType: FileType | null;
|
|
59
|
+
mimeType: string | null;
|
|
60
|
+
source: string | null;
|
|
61
|
+
fileRef: string | null;
|
|
62
|
+
clientRef: string | null;
|
|
63
|
+
jobId: string | null;
|
|
64
|
+
wfPhase: string | null;
|
|
65
|
+
wfKind: string | null;
|
|
66
|
+
originalArtifact: Artifact | null;
|
|
67
|
+
/**
|
|
68
|
+
* OMITTED (undefined) whenever `outputArtifacts` is non-empty — the
|
|
69
|
+
* formatter suppresses them once outputs exist.
|
|
70
|
+
*/
|
|
71
|
+
inputArtifact?: Artifact | null;
|
|
72
|
+
currentArtifact?: Artifact | null;
|
|
73
|
+
outputArtifacts: Artifact[];
|
|
74
|
+
steps: Step[];
|
|
75
|
+
/** Only when the rule defines cardinality slots (e.g. 'Front'/'Back'). */
|
|
76
|
+
slot?: string | null;
|
|
77
|
+
}
|
|
78
|
+
/** Written at finalization; present on non-lean reads of terminal jobs. */
|
|
79
|
+
interface JobSummary {
|
|
80
|
+
id: string;
|
|
81
|
+
domainIdx: number;
|
|
82
|
+
status: JobStatus;
|
|
83
|
+
outcome: Outcome | null;
|
|
84
|
+
ruleId: string | null;
|
|
85
|
+
channel: string | null;
|
|
86
|
+
customerId: string | null;
|
|
87
|
+
orderId: string | null;
|
|
88
|
+
policy: {
|
|
89
|
+
onFail?: OnFailPolicy;
|
|
90
|
+
} | null;
|
|
91
|
+
metaData: Record<string, unknown> | null;
|
|
92
|
+
taskIds: string[];
|
|
93
|
+
sourceRefs: Array<{
|
|
94
|
+
taskId: string | null;
|
|
95
|
+
bucket: string;
|
|
96
|
+
key: string;
|
|
97
|
+
}>;
|
|
98
|
+
created: number | null;
|
|
99
|
+
finalized: string;
|
|
100
|
+
}
|
|
101
|
+
interface ResultHeader {
|
|
102
|
+
taskId: string;
|
|
103
|
+
fileRef: string | null;
|
|
104
|
+
source: string | null;
|
|
105
|
+
fileType: FileType | null;
|
|
106
|
+
mimeType: string | null;
|
|
107
|
+
status: JobStatus;
|
|
108
|
+
outcome: Outcome | null;
|
|
109
|
+
}
|
|
110
|
+
interface ValidateProfileResult {
|
|
111
|
+
requested: string | null;
|
|
112
|
+
matched: string | null;
|
|
113
|
+
profileName: string | null;
|
|
114
|
+
compliant: boolean;
|
|
115
|
+
checks: {
|
|
116
|
+
passed: number;
|
|
117
|
+
failed: number;
|
|
118
|
+
};
|
|
119
|
+
rules: {
|
|
120
|
+
passed: number;
|
|
121
|
+
failed: number;
|
|
122
|
+
};
|
|
123
|
+
failures: unknown[];
|
|
124
|
+
}
|
|
125
|
+
interface ValidateResult extends ResultHeader {
|
|
126
|
+
compliant: boolean;
|
|
127
|
+
profiles: ValidateProfileResult[];
|
|
128
|
+
}
|
|
129
|
+
interface PreflightResult extends ResultHeader {
|
|
130
|
+
report: Record<string, unknown> | null;
|
|
131
|
+
}
|
|
132
|
+
interface OptimizeResult extends ResultHeader {
|
|
133
|
+
output: {
|
|
134
|
+
bucket: string | null;
|
|
135
|
+
key: string | null;
|
|
136
|
+
sizeBytes: number | null;
|
|
137
|
+
downloadUrl: string | null;
|
|
138
|
+
expiresIn: number | null;
|
|
139
|
+
appliedFixes?: unknown;
|
|
140
|
+
skippedFixes?: unknown;
|
|
141
|
+
} | null;
|
|
142
|
+
}
|
|
143
|
+
interface Job {
|
|
144
|
+
id: string;
|
|
145
|
+
createdAt: string | null;
|
|
146
|
+
modifiedAt: string | null;
|
|
147
|
+
/** Set while pending (abandoned-intake TTL) or on previews; null after. */
|
|
148
|
+
expiresAt: string | null;
|
|
149
|
+
status: JobStatus;
|
|
150
|
+
outcome: Outcome | null;
|
|
151
|
+
channel: string | null;
|
|
152
|
+
ruleId: string | null;
|
|
153
|
+
/** Response-only — `POST /jobs` does not accept a workflowId. */
|
|
154
|
+
workflowId: string | null;
|
|
155
|
+
wfPhase: string | null;
|
|
156
|
+
wfStreamStatus: string | null;
|
|
157
|
+
metaData: Record<string, unknown> | null;
|
|
158
|
+
/** The job's finalized file set — the single download surface. */
|
|
159
|
+
deliverables: Artifact[];
|
|
160
|
+
tasks: Task[];
|
|
161
|
+
orderId: string | null;
|
|
162
|
+
customerId: string | null;
|
|
163
|
+
orderStatus: string | null;
|
|
164
|
+
orderDetails: Record<string, unknown> | null;
|
|
165
|
+
customerEmail: string | null;
|
|
166
|
+
/** Non-lean reads of terminal jobs only. */
|
|
167
|
+
summary?: JobSummary;
|
|
168
|
+
/** Non-lean reads only; keys present only for step types that ran. */
|
|
169
|
+
results?: {
|
|
170
|
+
validate?: ValidateResult[];
|
|
171
|
+
preflight?: PreflightResult[];
|
|
172
|
+
optimize?: OptimizeResult[];
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
/** `GET /jobs/{id}?expand=runs` — a different envelope, no `job` wrapper. */
|
|
176
|
+
interface JobRuns {
|
|
177
|
+
id: string;
|
|
178
|
+
status: JobStatus;
|
|
179
|
+
outcome: Outcome | null;
|
|
180
|
+
runs: Run[];
|
|
181
|
+
}
|
|
182
|
+
interface Run {
|
|
183
|
+
id: string;
|
|
184
|
+
name: string;
|
|
185
|
+
outcome: Outcome | null;
|
|
186
|
+
status: JobStatus;
|
|
187
|
+
hasOutput: boolean;
|
|
188
|
+
proofs: Array<{
|
|
189
|
+
url: string;
|
|
190
|
+
}>;
|
|
191
|
+
downloadUrl: string | null;
|
|
192
|
+
}
|
|
193
|
+
interface JobPage {
|
|
194
|
+
jobs: Job[];
|
|
195
|
+
nextKey?: string | null;
|
|
196
|
+
}
|
|
197
|
+
interface DeleteJobResult {
|
|
198
|
+
id: string;
|
|
199
|
+
taskIds?: string[];
|
|
200
|
+
[key: string]: unknown;
|
|
201
|
+
}
|
|
202
|
+
interface OrderResult {
|
|
203
|
+
success: boolean;
|
|
204
|
+
affectedJobIds: string[];
|
|
205
|
+
[key: string]: unknown;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Webhook helper.
|
|
210
|
+
*
|
|
211
|
+
* IMPORTANT — signing status: Filecheck's per-job `job.completed` webhooks
|
|
212
|
+
* are delivered UNSIGNED today; the signature scheme is not finalized. This
|
|
213
|
+
* helper is structured so that when signing ships (expected:
|
|
214
|
+
* `x-filecheck-signature: <hex>` = HMAC-SHA256 over the raw body),
|
|
215
|
+
* verification becomes the default without breaking changes. Until then,
|
|
216
|
+
* pass `{ verify: false }` — an explicit, temporary escape hatch — or a
|
|
217
|
+
* secret+header pair if you front the endpoint with your own signing proxy.
|
|
218
|
+
*
|
|
219
|
+
* Always pass the RAW request body (string/Buffer), never a re-serialized
|
|
220
|
+
* parsed object: `express.raw({ type: 'application/json' })`,
|
|
221
|
+
* `await request.text()`, etc.
|
|
222
|
+
*/
|
|
223
|
+
/** `job.completed` payload — the finalization summary spread + tasks[]. */
|
|
224
|
+
interface JobCompletedPayload {
|
|
225
|
+
id: string;
|
|
226
|
+
domainIdx: number;
|
|
227
|
+
status: JobStatus;
|
|
228
|
+
outcome: Outcome | null;
|
|
229
|
+
ruleId: string | null;
|
|
230
|
+
channel: string | null;
|
|
231
|
+
customerId: string | null;
|
|
232
|
+
orderId: string | null;
|
|
233
|
+
policy: {
|
|
234
|
+
onFail?: OnFailPolicy;
|
|
235
|
+
} | null;
|
|
236
|
+
metaData: Record<string, unknown> | null;
|
|
237
|
+
taskIds: string[];
|
|
238
|
+
sourceRefs: Array<{
|
|
239
|
+
taskId: string | null;
|
|
240
|
+
bucket: string;
|
|
241
|
+
key: string;
|
|
242
|
+
}>;
|
|
243
|
+
created: number | null;
|
|
244
|
+
finalized: string;
|
|
245
|
+
tasks: Array<{
|
|
246
|
+
id: string;
|
|
247
|
+
status: JobStatus | null;
|
|
248
|
+
outcome: Outcome | null;
|
|
249
|
+
mimeType: string | null;
|
|
250
|
+
fileType: string | null;
|
|
251
|
+
clientRef: string | null;
|
|
252
|
+
source: string | null;
|
|
253
|
+
fileRef: string | null;
|
|
254
|
+
sourceRef: {
|
|
255
|
+
bucket: string;
|
|
256
|
+
key: string;
|
|
257
|
+
} | null;
|
|
258
|
+
originalArtifact: Artifact | null;
|
|
259
|
+
outputArtifacts: Artifact[];
|
|
260
|
+
steps: Array<{
|
|
261
|
+
id: string;
|
|
262
|
+
type: string;
|
|
263
|
+
status: JobStatus;
|
|
264
|
+
outcome: Outcome | null;
|
|
265
|
+
reason: string | null;
|
|
266
|
+
outputs: unknown[];
|
|
267
|
+
ended: string | null;
|
|
268
|
+
}>;
|
|
269
|
+
}>;
|
|
270
|
+
}
|
|
271
|
+
/** `job.created` payload (subscription webhooks). */
|
|
272
|
+
interface JobCreatedPayload {
|
|
273
|
+
id: string;
|
|
274
|
+
status: JobStatus;
|
|
275
|
+
channel: string | null;
|
|
276
|
+
ruleId: string | null;
|
|
277
|
+
customerId: string | null;
|
|
278
|
+
orderId: string | null;
|
|
279
|
+
taskCount: number;
|
|
280
|
+
created: number | string | null;
|
|
281
|
+
[key: string]: unknown;
|
|
282
|
+
}
|
|
283
|
+
type WebhookEvent = {
|
|
284
|
+
type: 'job.completed';
|
|
285
|
+
payload: JobCompletedPayload;
|
|
286
|
+
verified: boolean;
|
|
287
|
+
} | {
|
|
288
|
+
type: 'job.created';
|
|
289
|
+
payload: JobCreatedPayload;
|
|
290
|
+
verified: boolean;
|
|
291
|
+
} | {
|
|
292
|
+
type: 'unknown';
|
|
293
|
+
payload: Record<string, unknown>;
|
|
294
|
+
verified: boolean;
|
|
295
|
+
};
|
|
296
|
+
interface ConstructEventOptions {
|
|
297
|
+
/**
|
|
298
|
+
* Set to `false` to accept an unsigned payload. TEMPORARY: required today
|
|
299
|
+
* because Filecheck webhooks are not yet signed. Once the signing scheme
|
|
300
|
+
* ships, omit this and pass the secret instead.
|
|
301
|
+
*/
|
|
302
|
+
verify?: boolean;
|
|
303
|
+
}
|
|
304
|
+
declare function computeSignature(secret: string, rawBody: string | Buffer): string;
|
|
305
|
+
/**
|
|
306
|
+
* Parse (and, when possible, verify) a webhook request into a typed event.
|
|
307
|
+
*
|
|
308
|
+
* Payloads carry no event-type envelope, so the type is detected from the
|
|
309
|
+
* payload shape: a finalization summary (`taskIds` + `finalized` + `tasks`)
|
|
310
|
+
* is `job.completed`; a creation stub (`taskCount`) is `job.created`.
|
|
311
|
+
*/
|
|
312
|
+
declare function constructEvent(rawBody: string | Buffer, signatureHeader?: string | null, secret?: string | null, options?: ConstructEventOptions): WebhookEvent;
|
|
313
|
+
declare const webhooks: {
|
|
314
|
+
constructEvent: typeof constructEvent;
|
|
315
|
+
computeSignature: typeof computeSignature;
|
|
316
|
+
};
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* Minimal HTTP abstraction. The whole SDK talks to this interface so an
|
|
320
|
+
* edge/Workers build only needs a different transport, not different
|
|
321
|
+
* resources.
|
|
322
|
+
*/
|
|
323
|
+
interface HttpRequest {
|
|
324
|
+
method: 'GET' | 'POST' | 'DELETE';
|
|
325
|
+
url: string;
|
|
326
|
+
headers: Record<string, string>;
|
|
327
|
+
/** JSON string, multipart form data, or nothing. */
|
|
328
|
+
body?: string | FormData;
|
|
329
|
+
timeoutMs: number;
|
|
330
|
+
}
|
|
331
|
+
interface HttpResponse {
|
|
332
|
+
status: number;
|
|
333
|
+
headers: {
|
|
334
|
+
get(name: string): string | null;
|
|
335
|
+
};
|
|
336
|
+
text: string;
|
|
337
|
+
}
|
|
338
|
+
interface HttpTransport {
|
|
339
|
+
/**
|
|
340
|
+
* Perform the request. Resolves for ANY HTTP status; rejects (with
|
|
341
|
+
* ConnectionError) only when no response was produced at all.
|
|
342
|
+
*/
|
|
343
|
+
request(req: HttpRequest): Promise<HttpResponse>;
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
type FetchLike = (url: string, init: {
|
|
347
|
+
method: string;
|
|
348
|
+
headers: Record<string, string>;
|
|
349
|
+
body?: string | FormData;
|
|
350
|
+
signal?: AbortSignal;
|
|
351
|
+
}) => Promise<{
|
|
352
|
+
status: number;
|
|
353
|
+
headers: {
|
|
354
|
+
get(name: string): string | null;
|
|
355
|
+
};
|
|
356
|
+
text(): Promise<string>;
|
|
357
|
+
}>;
|
|
358
|
+
|
|
359
|
+
interface RequestOptions {
|
|
360
|
+
query?: Record<string, string | number | boolean | undefined>;
|
|
361
|
+
body?: unknown;
|
|
362
|
+
/** Only idempotent requests are ever auto-retried. */
|
|
363
|
+
idempotent?: boolean;
|
|
364
|
+
}
|
|
365
|
+
/** Bound transport + auth. All resources go through this. */
|
|
366
|
+
declare class Requestor {
|
|
367
|
+
private readonly transport;
|
|
368
|
+
private readonly baseUrl;
|
|
369
|
+
private readonly secretKey;
|
|
370
|
+
private readonly timeoutMs;
|
|
371
|
+
private readonly maxRetries;
|
|
372
|
+
constructor(transport: HttpTransport, baseUrl: string, secretKey: string, timeoutMs: number, maxRetries: number);
|
|
373
|
+
raw(method: 'GET' | 'POST' | 'DELETE', path: string, options?: RequestOptions): Promise<HttpResponse>;
|
|
374
|
+
/** Request + parse. Throws a typed FilecheckError on any non-2xx. */
|
|
375
|
+
json<T>(method: 'GET' | 'POST' | 'DELETE', path: string, options?: RequestOptions): Promise<{
|
|
376
|
+
status: number;
|
|
377
|
+
data: T;
|
|
378
|
+
}>;
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
/**
|
|
382
|
+
* Request parameter types, aligned with the API's JSON schemas
|
|
383
|
+
* (`filecheck-api/_layers/mixins/nodejs/schemas/*.json`). Note the schemas
|
|
384
|
+
* use `additionalProperties: false` — unknown keys are 400s, which is why
|
|
385
|
+
* these types are closed rather than index-signatured.
|
|
386
|
+
*/
|
|
387
|
+
/** Exactly one of `url` | `file` (base64) | `fileRef` | `source` per source. */
|
|
388
|
+
interface SourceRef {
|
|
389
|
+
/** Public (or header-authenticated) URL to pull the file from. */
|
|
390
|
+
url?: string;
|
|
391
|
+
/** Inline base64 file content (≤ ~7 MB decoded; prefer uploads.create). */
|
|
392
|
+
file?: string;
|
|
393
|
+
/** `upload_…` reference from `uploads.create()`. */
|
|
394
|
+
fileRef?: string;
|
|
395
|
+
/** Raw source pointer (advanced). */
|
|
396
|
+
source?: string;
|
|
397
|
+
/** Extra request headers used when fetching `url`. */
|
|
398
|
+
headers?: Record<string, string>;
|
|
399
|
+
}
|
|
400
|
+
interface JobStepInput {
|
|
401
|
+
type: string;
|
|
402
|
+
params?: Record<string, unknown>;
|
|
403
|
+
[key: string]: unknown;
|
|
404
|
+
}
|
|
405
|
+
interface CreateJobSource extends SourceRef {
|
|
406
|
+
/** Pipeline for this source (1–16 steps). */
|
|
407
|
+
steps: JobStepInput[];
|
|
408
|
+
params?: Record<string, unknown>;
|
|
409
|
+
}
|
|
410
|
+
interface WebhookParam {
|
|
411
|
+
url: string;
|
|
412
|
+
headers?: Record<string, string>;
|
|
413
|
+
}
|
|
414
|
+
/** `POST /jobs`. NOTE: `workflowId` is not accepted — it is response-only. */
|
|
415
|
+
interface CreateJobParams {
|
|
416
|
+
sources: CreateJobSource[];
|
|
417
|
+
ruleId?: string;
|
|
418
|
+
channel?: 'api' | 'store' | 'admin';
|
|
419
|
+
customerId?: string;
|
|
420
|
+
orderId?: string;
|
|
421
|
+
policy?: {
|
|
422
|
+
onFail: OnFailPolicy;
|
|
423
|
+
};
|
|
424
|
+
webhook?: WebhookParam;
|
|
425
|
+
metaData?: Record<string, unknown>;
|
|
426
|
+
}
|
|
427
|
+
/** PDF validation profile codes accepted by `POST /jobs/validate`. */
|
|
428
|
+
type ValidateProfileCode = 'auto' | '1a' | '1b' | '2a' | '2b' | '2u' | '3a' | '3b' | '3u' | '4' | '4e' | '4f' | 'ua1' | 'ua2';
|
|
429
|
+
interface ValidateSource extends SourceRef {
|
|
430
|
+
profile?: ValidateProfileCode | ValidateProfileCode[];
|
|
431
|
+
name?: string;
|
|
432
|
+
mimeType?: string;
|
|
433
|
+
}
|
|
434
|
+
interface ValidateParams {
|
|
435
|
+
sources: ValidateSource[];
|
|
436
|
+
webhook?: WebhookParam;
|
|
437
|
+
metaData?: Record<string, unknown>;
|
|
438
|
+
}
|
|
439
|
+
interface PreflightSource extends SourceRef {
|
|
440
|
+
profileId?: string;
|
|
441
|
+
name?: string;
|
|
442
|
+
}
|
|
443
|
+
interface PreflightParams {
|
|
444
|
+
sources: PreflightSource[];
|
|
445
|
+
webhook?: WebhookParam;
|
|
446
|
+
metaData?: Record<string, unknown>;
|
|
447
|
+
}
|
|
448
|
+
interface FixSource extends SourceRef {
|
|
449
|
+
profileId?: string;
|
|
450
|
+
items?: unknown[];
|
|
451
|
+
}
|
|
452
|
+
interface FixParams {
|
|
453
|
+
sources: FixSource[];
|
|
454
|
+
/** Re-run preflight on the fixed output. */
|
|
455
|
+
repreflight?: boolean;
|
|
456
|
+
webhook?: WebhookParam;
|
|
457
|
+
metaData?: Record<string, unknown>;
|
|
458
|
+
}
|
|
459
|
+
interface PreviewsSource extends SourceRef {
|
|
460
|
+
params?: Record<string, unknown>;
|
|
461
|
+
}
|
|
462
|
+
interface PreviewsParams {
|
|
463
|
+
sources: PreviewsSource[];
|
|
464
|
+
webhook?: WebhookParam;
|
|
465
|
+
metaData?: Record<string, unknown>;
|
|
466
|
+
}
|
|
467
|
+
interface OptimizeSource extends SourceRef {
|
|
468
|
+
/** Namespaced options: `params.pdf` and/or `params.raster`. */
|
|
469
|
+
params: Record<string, unknown>;
|
|
470
|
+
}
|
|
471
|
+
interface OptimizeParams {
|
|
472
|
+
sources: OptimizeSource[];
|
|
473
|
+
webhook?: WebhookParam;
|
|
474
|
+
metaData?: Record<string, unknown>;
|
|
475
|
+
}
|
|
476
|
+
/**
|
|
477
|
+
* Wait normalization. The raw API inconsistently uses `sync: true`
|
|
478
|
+
* (jobs/preflight/previews/fix — async by default) and `async: true`
|
|
479
|
+
* (validate/optimize — sync by default); the SDK hides both behind `wait`.
|
|
480
|
+
*/
|
|
481
|
+
interface WaitOptions {
|
|
482
|
+
/**
|
|
483
|
+
* Wait for a terminal job before resolving. Defaults mirror each
|
|
484
|
+
* endpoint's API default: false for create/preflight/previews/fix,
|
|
485
|
+
* true for validate/optimize.
|
|
486
|
+
*/
|
|
487
|
+
wait?: boolean;
|
|
488
|
+
/**
|
|
489
|
+
* Total wait budget in ms (default 120 000). The server itself waits up
|
|
490
|
+
* to ~27 s; past that the SDK keeps polling `GET /jobs/{id}` client-side.
|
|
491
|
+
* Set 0 for server-side wait only (a 202 then resolves `pending: true`).
|
|
492
|
+
*/
|
|
493
|
+
waitTimeoutMs?: number;
|
|
494
|
+
}
|
|
495
|
+
/** Result of any submit method. `pending` means the job is not terminal yet. */
|
|
496
|
+
interface JobResult {
|
|
497
|
+
job: Job;
|
|
498
|
+
pending: boolean;
|
|
499
|
+
}
|
|
500
|
+
interface ListJobsParams {
|
|
501
|
+
limit?: number;
|
|
502
|
+
nextKey?: string;
|
|
503
|
+
preview?: boolean;
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
/**
|
|
507
|
+
* Pure server-side port of the Element's intake-status resolver
|
|
508
|
+
* (`filecheck/packages/core/src/data/job/display.js` — `intakeStatusFor`,
|
|
509
|
+
* terminal branch). The browser Element's `canProceed` is true exactly for
|
|
510
|
+
* the `ready` and `partial` states; this mirrors that gate over the REST
|
|
511
|
+
* Job shape.
|
|
512
|
+
*
|
|
513
|
+
* Known approximation: the Element resolves `onFail` per task file-type
|
|
514
|
+
* from the rule's accept flows; the REST response carries no rule snapshot,
|
|
515
|
+
* so only the job-level policy (`job.summary.policy.onFail`, default
|
|
516
|
+
* `reject`) applies here. For rules mixing per-file-type policies, pass
|
|
517
|
+
* `options.policy` explicitly.
|
|
518
|
+
*/
|
|
519
|
+
type VerifyState = 'ready' | 'partial' | 'rejected' | 'not_terminal';
|
|
520
|
+
type VerifyReason = 'not_terminal' | 'cannot_proceed' | 'workflow_mismatch';
|
|
521
|
+
interface VerifyOptions {
|
|
522
|
+
/** Assert the job ran the expected workflow (compared to `job.workflowId`). */
|
|
523
|
+
workflowId?: string;
|
|
524
|
+
/** Override the resolved onFail policy. */
|
|
525
|
+
policy?: OnFailPolicy;
|
|
526
|
+
/**
|
|
527
|
+
* Fail closed on `status: 'error'` jobs even when no task outcome is a
|
|
528
|
+
* fail. The browser Element fails open on transport errors; a server-side
|
|
529
|
+
* fulfillment gate usually shouldn't.
|
|
530
|
+
*/
|
|
531
|
+
strict?: boolean;
|
|
532
|
+
}
|
|
533
|
+
interface VerifyResult {
|
|
534
|
+
ok: boolean;
|
|
535
|
+
state: VerifyState;
|
|
536
|
+
job: Job;
|
|
537
|
+
reason?: VerifyReason;
|
|
538
|
+
}
|
|
539
|
+
declare function resolveVerify(job: Job, options?: VerifyOptions): VerifyResult;
|
|
540
|
+
|
|
541
|
+
declare class JobsResource {
|
|
542
|
+
private readonly requestor;
|
|
543
|
+
constructor(requestor: Requestor);
|
|
544
|
+
/**
|
|
545
|
+
* Canonical `POST /jobs`. Async by default; pass `wait: true` to resolve
|
|
546
|
+
* with a terminal job. Note the API does not accept a `workflowId` here —
|
|
547
|
+
* workflow-driven jobs are created through the browser Element.
|
|
548
|
+
*/
|
|
549
|
+
create(params: CreateJobParams & WaitOptions): Promise<JobResult>;
|
|
550
|
+
/** `POST /jobs/preflight` — async by default. */
|
|
551
|
+
preflight(params: PreflightParams & WaitOptions): Promise<JobResult>;
|
|
552
|
+
/** `POST /jobs/previews` — async by default. */
|
|
553
|
+
previews(params: PreviewsParams & WaitOptions): Promise<JobResult>;
|
|
554
|
+
/** `POST /jobs/fix` — async by default. */
|
|
555
|
+
fix(params: FixParams & WaitOptions): Promise<JobResult>;
|
|
556
|
+
/** `POST /jobs/validate` — waits by default. */
|
|
557
|
+
validate(params: ValidateParams & WaitOptions): Promise<JobResult>;
|
|
558
|
+
/** `POST /jobs/optimize` — waits by default. */
|
|
559
|
+
optimize(params: OptimizeParams & WaitOptions): Promise<JobResult>;
|
|
560
|
+
retrieve(id: string): Promise<Job>;
|
|
561
|
+
/** `?expand=runs` — flattened per-file summary with proof + download URLs. */
|
|
562
|
+
retrieveRuns(id: string): Promise<JobRuns>;
|
|
563
|
+
list(params?: ListJobsParams): Promise<JobPage>;
|
|
564
|
+
/** Auto-paginates over `list()` following `nextKey`. */
|
|
565
|
+
iterate(params?: ListJobsParams): AsyncGenerator<Job, void, undefined>;
|
|
566
|
+
del(id: string): Promise<DeleteJobResult>;
|
|
567
|
+
/** Poll `GET /jobs/{id}` until terminal. Throws FilecheckError on timeout. */
|
|
568
|
+
waitUntilTerminal(id: string, options?: {
|
|
569
|
+
timeoutMs?: number;
|
|
570
|
+
pollIntervalMs?: number;
|
|
571
|
+
}): Promise<Job>;
|
|
572
|
+
/**
|
|
573
|
+
* The server-side fulfillment gate: fetch the job and check that it is
|
|
574
|
+
* terminal and proceedable (the Element's `canProceed` equivalent), and —
|
|
575
|
+
* when `workflowId` is given — that it ran the expected workflow.
|
|
576
|
+
*/
|
|
577
|
+
verify(jobId: string, options?: VerifyOptions): Promise<VerifyResult>;
|
|
578
|
+
private submit;
|
|
579
|
+
private pollUntilTerminal;
|
|
580
|
+
}
|
|
581
|
+
|
|
582
|
+
/**
|
|
583
|
+
* Read-only library item. Beyond `id`, `enabled`, and `source`
|
|
584
|
+
* (`'domain'` rows shadow same-id `'store'` rows), payloads are free-form.
|
|
585
|
+
*/
|
|
586
|
+
interface LibraryItem {
|
|
587
|
+
id: string;
|
|
588
|
+
enabled?: boolean;
|
|
589
|
+
source?: 'domain' | 'store';
|
|
590
|
+
[key: string]: unknown;
|
|
591
|
+
}
|
|
592
|
+
/**
|
|
593
|
+
* Generic read-only resource for workflows / connectors / rules / profiles /
|
|
594
|
+
* optimize presets. Envelope keys differ per resource (and are not always
|
|
595
|
+
* the path name — optimize-presets uses `presets`).
|
|
596
|
+
*/
|
|
597
|
+
declare class LibraryResource {
|
|
598
|
+
private readonly requestor;
|
|
599
|
+
private readonly path;
|
|
600
|
+
private readonly listKey;
|
|
601
|
+
private readonly itemKey;
|
|
602
|
+
constructor(requestor: Requestor, path: string, listKey: string, itemKey: string);
|
|
603
|
+
list(): Promise<LibraryItem[]>;
|
|
604
|
+
retrieve(id: string): Promise<LibraryItem>;
|
|
605
|
+
}
|
|
606
|
+
|
|
607
|
+
declare class OrdersResource {
|
|
608
|
+
private readonly requestor;
|
|
609
|
+
constructor(requestor: Requestor);
|
|
610
|
+
/** `POST /orders/{id}` — attach/refresh order data on the tenant's jobs. */
|
|
611
|
+
create(orderId: string, params: Record<string, unknown>): Promise<OrderResult>;
|
|
612
|
+
}
|
|
613
|
+
|
|
614
|
+
type UploadInput = Blob | ArrayBuffer | ArrayBufferView | Buffer;
|
|
615
|
+
interface UploadOptions {
|
|
616
|
+
mimeType?: string;
|
|
617
|
+
fileName?: string;
|
|
618
|
+
}
|
|
619
|
+
interface UploadResult {
|
|
620
|
+
fileRef: string;
|
|
621
|
+
maxBytes: number;
|
|
622
|
+
expiresIn: number;
|
|
623
|
+
}
|
|
624
|
+
declare class UploadsResource {
|
|
625
|
+
private readonly requestor;
|
|
626
|
+
private readonly transport;
|
|
627
|
+
private readonly timeoutMs;
|
|
628
|
+
constructor(requestor: Requestor, transport: HttpTransport, timeoutMs: number);
|
|
629
|
+
/**
|
|
630
|
+
* Upload a file for later use as a job source (`{ fileRef }`). Performs
|
|
631
|
+
* both legs: `POST /uploads` for a presigned S3 POST, then the multipart
|
|
632
|
+
* upload itself. Max 500 MB.
|
|
633
|
+
*/
|
|
634
|
+
create(file: UploadInput, options?: UploadOptions): Promise<UploadResult>;
|
|
635
|
+
}
|
|
636
|
+
|
|
637
|
+
interface FilecheckClientOptions {
|
|
638
|
+
/** Default `https://api.filecheck.io`. */
|
|
639
|
+
baseUrl?: string;
|
|
640
|
+
/** Per-request timeout (default 60 000 ms). */
|
|
641
|
+
timeoutMs?: number;
|
|
642
|
+
/** Max auto-retries for idempotent (GET) requests (default 2). */
|
|
643
|
+
maxRetries?: number;
|
|
644
|
+
/** Inject a fetch implementation (tests, custom agents). */
|
|
645
|
+
fetch?: FetchLike;
|
|
646
|
+
/** Full transport override (edge runtimes). Wins over `fetch`. */
|
|
647
|
+
transport?: HttpTransport;
|
|
648
|
+
}
|
|
649
|
+
/** `sk_…abc4` — safe to include in error messages and logs. */
|
|
650
|
+
declare function maskKey(key: string): string;
|
|
651
|
+
declare class Filecheck {
|
|
652
|
+
readonly jobs: JobsResource;
|
|
653
|
+
readonly uploads: UploadsResource;
|
|
654
|
+
readonly orders: OrdersResource;
|
|
655
|
+
readonly workflows: LibraryResource;
|
|
656
|
+
readonly connectors: LibraryResource;
|
|
657
|
+
readonly rules: LibraryResource;
|
|
658
|
+
readonly profiles: LibraryResource;
|
|
659
|
+
readonly optimizePresets: LibraryResource;
|
|
660
|
+
readonly webhooks: {
|
|
661
|
+
constructEvent: typeof constructEvent;
|
|
662
|
+
computeSignature: typeof computeSignature;
|
|
663
|
+
};
|
|
664
|
+
constructor(secretKey: string, options?: FilecheckClientOptions);
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
/**
|
|
668
|
+
* Typed error hierarchy. The API has no machine-readable error codes — only
|
|
669
|
+
* an HTTP status and a human message — so handle errors by class/status,
|
|
670
|
+
* never by matching message text (server messages are unstable).
|
|
671
|
+
*
|
|
672
|
+
* Two error body shapes exist:
|
|
673
|
+
* - app errors: `{ "error": true, "message": "…" }`
|
|
674
|
+
* - API Gateway auth: `{ "message": "Unauthorized" | "Forbidden" }`
|
|
675
|
+
* plus occasional non-JSON bodies (HTML 502s from intermediaries).
|
|
676
|
+
*/
|
|
677
|
+
declare class FilecheckError extends Error {
|
|
678
|
+
readonly status?: number;
|
|
679
|
+
readonly requestId?: string;
|
|
680
|
+
/** Parsed response body, when it was JSON. */
|
|
681
|
+
readonly body?: unknown;
|
|
682
|
+
constructor(message: string, options?: {
|
|
683
|
+
status?: number;
|
|
684
|
+
requestId?: string;
|
|
685
|
+
body?: unknown;
|
|
686
|
+
});
|
|
687
|
+
}
|
|
688
|
+
/** 401 / 403 — bad, disabled, or wrong-kind key. */
|
|
689
|
+
declare class AuthenticationError extends FilecheckError {
|
|
690
|
+
}
|
|
691
|
+
/** 400 — the request body failed validation. */
|
|
692
|
+
declare class InvalidRequestError extends FilecheckError {
|
|
693
|
+
}
|
|
694
|
+
/** 404 — job / resource not found. */
|
|
695
|
+
declare class NotFoundError extends FilecheckError {
|
|
696
|
+
}
|
|
697
|
+
/** 429 — throttled (not emitted by the app today; handled defensively). */
|
|
698
|
+
declare class RateLimitError extends FilecheckError {
|
|
699
|
+
}
|
|
700
|
+
/** 5xx or unexpected status. */
|
|
701
|
+
declare class APIError extends FilecheckError {
|
|
702
|
+
}
|
|
703
|
+
/** The request never produced an HTTP response (network failure, timeout). */
|
|
704
|
+
declare class ConnectionError extends FilecheckError {
|
|
705
|
+
}
|
|
706
|
+
/** Webhook signature verification failed. */
|
|
707
|
+
declare class WebhookSignatureError extends FilecheckError {
|
|
708
|
+
}
|
|
709
|
+
|
|
710
|
+
export { APIError, type Artifact, AuthenticationError, ConnectionError, type ConstructEventOptions, type CreateJobParams, type CreateJobSource, type DeleteJobResult, type FetchLike, type FileType, Filecheck, type FilecheckClientOptions, FilecheckError, type FixParams, type FixSource, type HttpRequest, type HttpResponse, type HttpTransport, InvalidRequestError, type Job, type JobCompletedPayload, type JobCreatedPayload, type JobPage, type JobResult, type JobRuns, type JobStatus, type JobStepInput, type JobSummary, type LibraryItem, type ListJobsParams, NotFoundError, type OnFailPolicy, type OptimizeParams, type OptimizeResult, type OptimizeSource, type OrderResult, type Outcome, type PreflightParams, type PreflightResult, type PreflightSource, type PreviewsParams, type PreviewsSource, RateLimitError, type Run, type SourceRef, type Step, type StepType, TERMINAL_STATUSES, type Task, type UploadInput, type UploadOptions, type UploadResult, type ValidateParams, type ValidateProfileCode, type ValidateProfileResult, type ValidateResult, type ValidateSource, type VerifyOptions, type VerifyReason, type VerifyResult, type VerifyState, type WaitOptions, type WebhookEvent, type WebhookParam, WebhookSignatureError, computeSignature, constructEvent, Filecheck as default, isTerminal, maskKey, resolveVerify, webhooks };
|