typizer 0.1.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/CHANGELOG.md +76 -0
- package/README.md +273 -134
- package/dist/client.d.ts +323 -0
- package/dist/client.js +629 -0
- package/dist/core.d.ts +109 -0
- package/dist/core.js +339 -0
- package/dist/errors.d.ts +146 -0
- package/dist/errors.js +281 -0
- package/dist/files.d.ts +42 -0
- package/dist/files.js +159 -0
- package/dist/gen/index.d.ts +2 -2
- package/dist/gen/index.js +1 -1
- package/dist/gen/sdk.gen.d.ts +509 -5
- package/dist/gen/sdk.gen.js +893 -4
- package/dist/gen/types.gen.d.ts +4279 -913
- package/dist/index.d.ts +26 -3
- package/dist/index.js +33 -4
- package/dist/pagination.d.ts +30 -0
- package/dist/pagination.js +49 -0
- package/dist/run.d.ts +50 -0
- package/dist/run.js +45 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +2 -0
- package/dist/webhooks.d.ts +40 -0
- package/dist/webhooks.js +208 -0
- package/package.json +3 -1
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `Typizer` client (SPEC.md): one entry point, resources as namespaces, `extract` in one call,
|
|
3
|
+
* retries, idempotency keys, typed errors, pagination and webhooks.
|
|
4
|
+
*/
|
|
5
|
+
import { APIPromise, type AppInfo, type Logger, type LogLevel, type Query, type Req, type RequestOptions, type Shared, Transport, type WithResponse } from './core.js';
|
|
6
|
+
import { type FileInput, type Uploadable } from './files.js';
|
|
7
|
+
import type { Balance, Batch, CatalogEntry, CatalogEntryBrief, CatalogFavorite, CatalogPublisher, CatalogReport, CatalogUpdate, CatalogVersionBrief, DeletedFile, DeletedTypizer, DeletedWebhookEndpoint, File as FileObject, Me, Organization, Status, TypizerDraft, Typizer as TypizerObject, TypizerVersion, Usage, WebhookDelivery, WebhookEndpoint, WebhookEventType } from './gen/types.gen.js';
|
|
8
|
+
import { PagePromise } from './pagination.js';
|
|
9
|
+
import { type TypizerRun } from './run.js';
|
|
10
|
+
export declare const DEFAULT_BASE_URL = "https://api.typizer.ru";
|
|
11
|
+
/** Settings of a `Typizer` client (SPEC §2.1). */
|
|
12
|
+
export interface TypizerOptions {
|
|
13
|
+
/** API key (`tz_live_…`/`tz_test_…`); default `TYPIZER_API_KEY`. */
|
|
14
|
+
apiKey?: string;
|
|
15
|
+
/** Default `TYPIZER_BASE_URL`, else `https://api.typizer.ru`. */
|
|
16
|
+
baseUrl?: string;
|
|
17
|
+
/** Timeout of one HTTP attempt in milliseconds (default 75 000). */
|
|
18
|
+
timeout?: number;
|
|
19
|
+
/** Automatic retries (default 2, so up to 3 attempts). */
|
|
20
|
+
maxRetries?: number;
|
|
21
|
+
/** The longest `Retry-After` the client waits out, in milliseconds (default 60 000). */
|
|
22
|
+
maxRetryDelay?: number;
|
|
23
|
+
/** Your `fetch` (a proxy, a corporate root certificate, tests). */
|
|
24
|
+
fetch?: typeof fetch;
|
|
25
|
+
/** A proxy URL (`http://user:pass@proxy:3128`); needs the optional `undici` package. */
|
|
26
|
+
proxy?: string;
|
|
27
|
+
/** Headers for every request (cannot override `Authorization`). */
|
|
28
|
+
defaultHeaders?: Record<string, string>;
|
|
29
|
+
/** Your application, appended to `User-Agent`. */
|
|
30
|
+
appInfo?: AppInfo;
|
|
31
|
+
/** A `console`-compatible logger (default `console`). */
|
|
32
|
+
logger?: Logger;
|
|
33
|
+
/** Default `TYPIZER_LOG`, else `warn`. */
|
|
34
|
+
logLevel?: LogLevel;
|
|
35
|
+
}
|
|
36
|
+
export type Format = 'json' | 'xml' | 'csv' | 'xlsx';
|
|
37
|
+
export type Mode = 'standard' | 'precise';
|
|
38
|
+
type JsonSchema = Record<string, unknown> | string;
|
|
39
|
+
/** The document and the schema of a run (SPEC §4). */
|
|
40
|
+
export interface RunParams {
|
|
41
|
+
/** A path, `Blob`/`File`, bytes or a stream (sent in the same request), or `{ url }` / `{ fileId }`. */
|
|
42
|
+
file?: FileInput;
|
|
43
|
+
/** A public `http(s)` URL of the document. */
|
|
44
|
+
url?: string;
|
|
45
|
+
/** An uploaded file's id (`file_…`). */
|
|
46
|
+
fileId?: string;
|
|
47
|
+
/** The file name for bytes or a stream (default: from the path, else `document`). */
|
|
48
|
+
filename?: string;
|
|
49
|
+
/** A JSON Schema object (or JSON text); its property order is kept. */
|
|
50
|
+
schema?: JsonSchema;
|
|
51
|
+
/** A catalog schema: `schet-faktura`, `schet-faktura@1`, `acme/akt-sverki@1.2.0`. */
|
|
52
|
+
catalog?: string;
|
|
53
|
+
/** A saved typizer: `tz_…` or the object. */
|
|
54
|
+
typizer?: string | {
|
|
55
|
+
id: string;
|
|
56
|
+
};
|
|
57
|
+
/** Extra instructions (only with `schema`). */
|
|
58
|
+
instructions?: string;
|
|
59
|
+
mode?: Mode;
|
|
60
|
+
format?: Format;
|
|
61
|
+
metadata?: Record<string, string>;
|
|
62
|
+
/** An `https` URL for the `run.succeeded`/`run.failed` webhook of this run. */
|
|
63
|
+
webhookUrl?: string;
|
|
64
|
+
idempotencyKey?: string;
|
|
65
|
+
signal?: AbortSignal;
|
|
66
|
+
}
|
|
67
|
+
export interface WaitParams {
|
|
68
|
+
/** How long to wait in total, in milliseconds (default 300 000). */
|
|
69
|
+
timeout?: number;
|
|
70
|
+
/** The first pause between polls, in milliseconds (default 1000; grows ×1.5 up to 5000). */
|
|
71
|
+
pollInterval?: number;
|
|
72
|
+
signal?: AbortSignal;
|
|
73
|
+
}
|
|
74
|
+
export interface ExtractParams extends RunParams, WaitParams {
|
|
75
|
+
}
|
|
76
|
+
export interface CreateRunParams extends RunParams {
|
|
77
|
+
/** Ask the server to hold the request until the run finishes, up to 60 seconds. */
|
|
78
|
+
wait?: number;
|
|
79
|
+
}
|
|
80
|
+
export interface ListParams {
|
|
81
|
+
limit?: number;
|
|
82
|
+
}
|
|
83
|
+
export interface RunListParams extends ListParams {
|
|
84
|
+
status?: string;
|
|
85
|
+
typizerId?: string;
|
|
86
|
+
batchId?: string;
|
|
87
|
+
source?: string;
|
|
88
|
+
createdAfter?: string | Date;
|
|
89
|
+
createdBefore?: string | Date;
|
|
90
|
+
}
|
|
91
|
+
export interface TypizerCreateParams {
|
|
92
|
+
name: string;
|
|
93
|
+
schema: JsonSchema;
|
|
94
|
+
description?: string | null;
|
|
95
|
+
instructions?: string;
|
|
96
|
+
defaultFormat?: Format;
|
|
97
|
+
mode?: Mode;
|
|
98
|
+
}
|
|
99
|
+
export type TypizerUpdateParams = Partial<TypizerCreateParams>;
|
|
100
|
+
export interface CatalogListParams extends ListParams {
|
|
101
|
+
q?: string;
|
|
102
|
+
category?: string;
|
|
103
|
+
kind?: 'official' | 'community' | (string & {});
|
|
104
|
+
publisher?: string;
|
|
105
|
+
favorites?: boolean;
|
|
106
|
+
sort?: string;
|
|
107
|
+
}
|
|
108
|
+
export interface BatchCreateParams {
|
|
109
|
+
/** The typizer: `tz_…` or the object. */
|
|
110
|
+
typizer: string | {
|
|
111
|
+
id: string;
|
|
112
|
+
};
|
|
113
|
+
/** Local documents, uploaded in the same request (one may be a `.zip`). */
|
|
114
|
+
files?: Array<Uploadable | {
|
|
115
|
+
file: Uploadable;
|
|
116
|
+
filename?: string;
|
|
117
|
+
}>;
|
|
118
|
+
/** Or files uploaded before. */
|
|
119
|
+
fileIds?: string[];
|
|
120
|
+
format?: Format;
|
|
121
|
+
mode?: Mode;
|
|
122
|
+
metadata?: Record<string, string>;
|
|
123
|
+
}
|
|
124
|
+
/** The Typizer API client. One per application: it is safe to share and reuses connections. */
|
|
125
|
+
export declare class TypizerClient {
|
|
126
|
+
#private;
|
|
127
|
+
/** Webhook signature verification, without a client: `Typizer.webhooks.verify(body, headers, secret)`. */
|
|
128
|
+
static readonly webhooks: {
|
|
129
|
+
readonly verify: typeof import("./webhooks.js").verifyWebhook;
|
|
130
|
+
readonly isValid: typeof import("./webhooks.js").isValidWebhook;
|
|
131
|
+
};
|
|
132
|
+
readonly runs: Runs;
|
|
133
|
+
readonly files: Files;
|
|
134
|
+
readonly typizers: Typizers;
|
|
135
|
+
readonly catalog: Catalog;
|
|
136
|
+
readonly batches: Batches;
|
|
137
|
+
readonly webhookEndpoints: WebhookEndpoints;
|
|
138
|
+
/** Same as the static `Typizer.webhooks`. */
|
|
139
|
+
readonly webhooks: {
|
|
140
|
+
readonly verify: typeof import("./webhooks.js").verifyWebhook;
|
|
141
|
+
readonly isValid: typeof import("./webhooks.js").isValidWebhook;
|
|
142
|
+
};
|
|
143
|
+
/** @internal */
|
|
144
|
+
readonly _transport: Transport;
|
|
145
|
+
constructor(options?: TypizerOptions, shared?: Shared);
|
|
146
|
+
/** A copy with other settings that shares the connections and state. */
|
|
147
|
+
withOptions(options: Omit<TypizerOptions, 'apiKey' | 'baseUrl' | 'fetch' | 'proxy'>): TypizerClient;
|
|
148
|
+
/** @internal */
|
|
149
|
+
_call<T, R = T>(req: Req | (() => Promise<Req>), opts?: RequestOptions, map?: (raw: R) => T): APIPromise<T>;
|
|
150
|
+
/** @internal */
|
|
151
|
+
_send<T, R = T>(req: Req | (() => Promise<Req>), opts?: RequestOptions, map?: (raw: R) => T): Promise<WithResponse<T>>;
|
|
152
|
+
/** @internal */
|
|
153
|
+
_list<T, R = T>(path: string, query: Query, cursorParam: 'starting_after' | 'cursor', opts?: RequestOptions, map?: (raw: R) => T): PagePromise<T>;
|
|
154
|
+
/**
|
|
155
|
+
* Processes a document and waits for the result — the main task in one call (SPEC §4):
|
|
156
|
+
* `const run = await client.extract({ file: 'invoice.pdf', schema })`.
|
|
157
|
+
*
|
|
158
|
+
* Pass exactly one of `schema`, `catalog`, `typizer`. A local file goes in the same request.
|
|
159
|
+
* Returns the succeeded run; a failed run is a `RunFailedError`, a run still going after
|
|
160
|
+
* `timeout` (300 s) a `WaitTimeoutError` (the run goes on and is billed).
|
|
161
|
+
*/
|
|
162
|
+
extract<TOutput = unknown>(params: ExtractParams, options?: RequestOptions): APIPromise<TypizerRun<TOutput>>;
|
|
163
|
+
/** Who the API key belongs to (`GET /v1/me`). */
|
|
164
|
+
me(options?: RequestOptions): APIPromise<Me>;
|
|
165
|
+
/** Pages on the balance (`GET /v1/balance`). */
|
|
166
|
+
balance(options?: RequestOptions): APIPromise<Balance>;
|
|
167
|
+
/** Usage by day, typizer or key (`GET /v1/usage`). */
|
|
168
|
+
usage(params?: {
|
|
169
|
+
from?: string;
|
|
170
|
+
to?: string;
|
|
171
|
+
groupBy?: 'day' | 'typizer' | 'key';
|
|
172
|
+
}, options?: RequestOptions): APIPromise<Usage>;
|
|
173
|
+
/** The key's organization (`GET /v1/organization`). */
|
|
174
|
+
organization(options?: RequestOptions): APIPromise<Organization>;
|
|
175
|
+
/** Service status and maintenance (`GET /v1/status`). */
|
|
176
|
+
status(options?: RequestOptions): APIPromise<Status>;
|
|
177
|
+
toJSON(): {
|
|
178
|
+
apiKey: string;
|
|
179
|
+
baseUrl: string;
|
|
180
|
+
};
|
|
181
|
+
toString(): string;
|
|
182
|
+
}
|
|
183
|
+
declare abstract class Resource {
|
|
184
|
+
protected readonly c: TypizerClient;
|
|
185
|
+
constructor(client: TypizerClient);
|
|
186
|
+
}
|
|
187
|
+
/** `client.runs`: documents processed by a schema. */
|
|
188
|
+
export declare class Runs extends Resource {
|
|
189
|
+
/** @internal Builds the request that creates a run (argument errors before the network). */
|
|
190
|
+
_request(method: string, params: RunParams, wait: number | undefined): Promise<Req>;
|
|
191
|
+
/** @internal The polling loop of SPEC §4.4. */
|
|
192
|
+
_poll<TOutput>(run: TypizerRun<TOutput>, start: number, deadline: number, pollInterval: number | undefined, options: RequestOptions): Promise<TypizerRun<TOutput>>;
|
|
193
|
+
/**
|
|
194
|
+
* Starts a run without waiting (unless `wait` asks the server to hold the request up to 60 s):
|
|
195
|
+
* `POST /v1/extract`, or `POST /v1/typizers/{id}/runs` with `typizer`.
|
|
196
|
+
*/
|
|
197
|
+
create<TOutput = unknown>(params: CreateRunParams, options?: RequestOptions): APIPromise<TypizerRun<TOutput>>;
|
|
198
|
+
/** A run (`GET /v1/runs/{id}`). */
|
|
199
|
+
get<TOutput = unknown>(id: string, options?: RequestOptions): APIPromise<TypizerRun<TOutput>>;
|
|
200
|
+
/**
|
|
201
|
+
* Waits for a run to finish and returns it — `succeeded` or `failed` (only a wait that runs
|
|
202
|
+
* out throws: `WaitTimeoutError`).
|
|
203
|
+
*/
|
|
204
|
+
wait<TOutput = unknown>(id: string, params?: WaitParams, options?: RequestOptions): APIPromise<TypizerRun<TOutput>>;
|
|
205
|
+
/** Runs, newest first; `for await` walks all pages (`GET /v1/runs`). */
|
|
206
|
+
list(params?: RunListParams, options?: RequestOptions): PagePromise<TypizerRun>;
|
|
207
|
+
/** The result in a file format (`GET /v1/runs/{id}/output`): a `Response` to read or stream. */
|
|
208
|
+
output(id: string, params?: {
|
|
209
|
+
format?: Format;
|
|
210
|
+
}, options?: RequestOptions): APIPromise<Response>;
|
|
211
|
+
/** Runs a failed run again (`POST /v1/runs/{id}/retry`). */
|
|
212
|
+
retry<TOutput = unknown>(id: string, options?: RequestOptions): APIPromise<TypizerRun<TOutput>>;
|
|
213
|
+
}
|
|
214
|
+
/** `client.files`: uploaded documents. */
|
|
215
|
+
export declare class Files extends Resource {
|
|
216
|
+
/** Uploads a document (`POST /v1/files`); usually not needed — `extract` takes the file itself. */
|
|
217
|
+
upload(file: Uploadable, params?: {
|
|
218
|
+
filename?: string;
|
|
219
|
+
}, options?: RequestOptions): APIPromise<FileObject>;
|
|
220
|
+
get(id: string, options?: RequestOptions): APIPromise<FileObject>;
|
|
221
|
+
delete(id: string, options?: RequestOptions): APIPromise<DeletedFile>;
|
|
222
|
+
/** The file's bytes: a `Response` to read or stream. */
|
|
223
|
+
content(id: string, options?: RequestOptions): APIPromise<Response>;
|
|
224
|
+
}
|
|
225
|
+
declare class TypizerVersions extends Resource {
|
|
226
|
+
list(typizerId: string, params?: ListParams, options?: RequestOptions): PagePromise<TypizerVersion>;
|
|
227
|
+
get(typizerId: string, version: number, options?: RequestOptions): APIPromise<TypizerVersion>;
|
|
228
|
+
}
|
|
229
|
+
declare class TypizerCatalogUpdate extends Resource {
|
|
230
|
+
/** What a catalog update would change (`GET /v1/typizers/{id}/catalog_update`). */
|
|
231
|
+
get(typizerId: string, params?: {
|
|
232
|
+
version?: string;
|
|
233
|
+
}, options?: RequestOptions): APIPromise<CatalogUpdate>;
|
|
234
|
+
/** Applies a catalog update (`POST /v1/typizers/{id}/catalog_update`). */
|
|
235
|
+
apply(typizerId: string, params: {
|
|
236
|
+
version: string;
|
|
237
|
+
paths?: string[];
|
|
238
|
+
}, options?: RequestOptions): APIPromise<TypizerObject>;
|
|
239
|
+
}
|
|
240
|
+
/** `client.typizers`: saved schemas. */
|
|
241
|
+
export declare class Typizers extends Resource {
|
|
242
|
+
readonly versions: TypizerVersions;
|
|
243
|
+
readonly catalogUpdate: TypizerCatalogUpdate;
|
|
244
|
+
create(params: TypizerCreateParams, options?: RequestOptions): APIPromise<TypizerObject>;
|
|
245
|
+
get(id: string, options?: RequestOptions): APIPromise<TypizerObject>;
|
|
246
|
+
update(id: string, params: TypizerUpdateParams, options?: RequestOptions): APIPromise<TypizerObject>;
|
|
247
|
+
delete(id: string, options?: RequestOptions): APIPromise<DeletedTypizer>;
|
|
248
|
+
list(params?: ListParams, options?: RequestOptions): PagePromise<TypizerObject>;
|
|
249
|
+
/** Drafts a schema from a description and/or a sample file (`POST /v1/typizers/generate`). */
|
|
250
|
+
generate(params: {
|
|
251
|
+
description?: string;
|
|
252
|
+
fileId?: string;
|
|
253
|
+
}, options?: RequestOptions): APIPromise<TypizerDraft>;
|
|
254
|
+
/** The typizer's XSD (`GET /v1/typizers/{id}/xsd`): a `Response`. */
|
|
255
|
+
xsd(id: string, options?: RequestOptions): APIPromise<Response>;
|
|
256
|
+
}
|
|
257
|
+
declare class CatalogPublishers extends Resource {
|
|
258
|
+
get(slug: string, options?: RequestOptions): APIPromise<CatalogPublisher>;
|
|
259
|
+
}
|
|
260
|
+
/** `client.catalog`: ready-made schemas (official and community). */
|
|
261
|
+
export declare class Catalog extends Resource {
|
|
262
|
+
#private;
|
|
263
|
+
readonly publishers: CatalogPublishers;
|
|
264
|
+
list(params?: CatalogListParams, options?: RequestOptions): PagePromise<CatalogEntryBrief>;
|
|
265
|
+
/** A catalog schema: `schet-faktura`, `schet-faktura@1`, `cat_…`, `acme/akt-sverki@1.2.0`. */
|
|
266
|
+
get(ref: string, params?: {
|
|
267
|
+
version?: string;
|
|
268
|
+
}, options?: RequestOptions): APIPromise<CatalogEntry>;
|
|
269
|
+
/** Every version of a catalog schema (not paginated). */
|
|
270
|
+
versions(ref: string, options?: RequestOptions): APIPromise<CatalogVersionBrief[]>;
|
|
271
|
+
/** Adds a catalog schema to your typizers as it is. */
|
|
272
|
+
install(ref: string, params?: {
|
|
273
|
+
version?: string;
|
|
274
|
+
name?: string;
|
|
275
|
+
}, options?: RequestOptions): APIPromise<TypizerObject>;
|
|
276
|
+
/** Creates your own typizer from a catalog schema, to change it. */
|
|
277
|
+
fork(ref: string, params?: {
|
|
278
|
+
version?: string;
|
|
279
|
+
name?: string;
|
|
280
|
+
}, options?: RequestOptions): APIPromise<TypizerObject>;
|
|
281
|
+
favorite(ref: string, options?: RequestOptions): APIPromise<CatalogFavorite>;
|
|
282
|
+
unfavorite(ref: string, options?: RequestOptions): APIPromise<CatalogFavorite>;
|
|
283
|
+
/** Reports a catalog schema to the moderators. */
|
|
284
|
+
report(ref: string, params: {
|
|
285
|
+
reason: 'pii' | 'plagiarism' | 'broken' | 'spam' | 'other';
|
|
286
|
+
details?: string;
|
|
287
|
+
version?: string;
|
|
288
|
+
}, options?: RequestOptions): APIPromise<CatalogReport>;
|
|
289
|
+
}
|
|
290
|
+
/** `client.batches`: one typizer over many files. */
|
|
291
|
+
export declare class Batches extends Resource {
|
|
292
|
+
create(params: BatchCreateParams, options?: RequestOptions): APIPromise<Batch>;
|
|
293
|
+
get(id: string, options?: RequestOptions): APIPromise<Batch>;
|
|
294
|
+
list(params?: ListParams, options?: RequestOptions): PagePromise<Batch>;
|
|
295
|
+
/** All results of a batch in one file (`GET /v1/batches/{id}/export`): a `Response`. */
|
|
296
|
+
export(id: string, params?: {
|
|
297
|
+
format?: Format;
|
|
298
|
+
}, options?: RequestOptions): APIPromise<Response>;
|
|
299
|
+
}
|
|
300
|
+
declare class WebhookDeliveries extends Resource {
|
|
301
|
+
list(endpointId: string, params?: ListParams, options?: RequestOptions): PagePromise<WebhookDelivery>;
|
|
302
|
+
retry(deliveryId: string, options?: RequestOptions): APIPromise<WebhookDelivery>;
|
|
303
|
+
}
|
|
304
|
+
/** `client.webhookEndpoints`: where Typizer sends webhooks. */
|
|
305
|
+
export declare class WebhookEndpoints extends Resource {
|
|
306
|
+
readonly deliveries: WebhookDeliveries;
|
|
307
|
+
/** Creates an endpoint; `secret` comes only in this response (a replay returns `secret: null`). */
|
|
308
|
+
create(params: {
|
|
309
|
+
url: string;
|
|
310
|
+
events?: Array<WebhookEventType | (string & {})>;
|
|
311
|
+
}, options?: RequestOptions): APIPromise<WebhookEndpoint>;
|
|
312
|
+
get(id: string, options?: RequestOptions): APIPromise<WebhookEndpoint>;
|
|
313
|
+
update(id: string, params: {
|
|
314
|
+
url?: string;
|
|
315
|
+
events?: Array<WebhookEventType | (string & {})>;
|
|
316
|
+
status?: 'active' | 'disabled';
|
|
317
|
+
}, options?: RequestOptions): APIPromise<WebhookEndpoint>;
|
|
318
|
+
delete(id: string, options?: RequestOptions): APIPromise<DeletedWebhookEndpoint>;
|
|
319
|
+
list(params?: ListParams, options?: RequestOptions): PagePromise<WebhookEndpoint>;
|
|
320
|
+
/** Sends a test event to the endpoint. */
|
|
321
|
+
test(id: string, options?: RequestOptions): APIPromise<WebhookDelivery>;
|
|
322
|
+
}
|
|
323
|
+
export {};
|