@adminiumjs/add-on-contracts 0.2.5 → 0.2.7

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.
@@ -0,0 +1,547 @@
1
+ /**
2
+ * `document-render@1` (34-invoices-add-on.md §4, Appendices A and B) — the
3
+ * fourth contract, and the first one Adminium ITSELF consumes.
4
+ *
5
+ * It provides KINDS OF DOCUMENT an add-on can describe — an outline of slots,
6
+ * every label written in all eight compiled locales — and render to BYTES. The
7
+ * consumer is the engine document pipeline (profiles, the record trigger, the
8
+ * `document.render` job, the `/documents` routes), which is the first
9
+ * production read of `runtime.providers`: a provider is selected by the
10
+ * profile's add-on key, never by `resolveProvider`'s lowest-key choice.
11
+ *
12
+ * ── THE SUBJECT IS THE ONLY DOOR (31 A.1's rule, applied to a contract) ─────
13
+ *
14
+ * A provider receives VALUES and returns BYTES. It gets no database handle, no
15
+ * network, and — the one that gets forgotten — no clock: `subject.now` is the
16
+ * only time it may read, which is what makes 25 D12's byte-identical claim
17
+ * testable rather than aspirational. `describeDocumentRenderer` renders twice
18
+ * and compares every byte.
19
+ *
20
+ * ── BYTES, NOT A `FileRef` ─────────────────────────────────────────────────
21
+ *
22
+ * {@link RenderedDocument.bytes} is a `Uint8Array`. `FileRef.bytes`
23
+ * (`common.ts:14,22`) is a COUNT, and a provider that returned one would be
24
+ * claiming it had already stored the file — which it cannot do, having no file
25
+ * seam. The engine stores what comes back; the provider never does.
26
+ *
27
+ * ── PER-KIND `formats` AND `coverage`, AND WHY THEY ARE ON THE KIND ────────
28
+ *
29
+ * "HTML always, PDF always" is NOT this contract's law. `label-sheet` is
30
+ * `['pdf']` with nothing to say in HTML; `receipt` draws on 80 mm paper no A4
31
+ * consumer wants. And a writer that draws Helvetica's WinAnsi repertoire
32
+ * cannot draw Arabic or Han — so a kind declares the glyphs it covers and
33
+ * REFUSES what it cannot draw, typed, as {@link DocumentError} `LATIN_ONLY`
34
+ * carrying the offending glyphs. A silent drop would ship an invoice with a
35
+ * customer's name missing letters (34 D6, O11, O12).
36
+ *
37
+ * ── THE `body` CHANNEL IS A ONE-WAY DOOR, AND IT IS OPEN ───────────────────
38
+ *
39
+ * §4.3 ships this module verbatim into eighteen repos before the first
40
+ * provider exists, so a field added later is a second eighteen-repo ceremony
41
+ * plus a second contract release. {@link RenderInput.body} is therefore here in
42
+ * the first release. Its shape is O28(a2) — ruled 2026-09-07 as **D54**: an
43
+ * opaque `Readonly<Record<string, unknown>>` whose schema the PROVIDER owns. A
44
+ * typed union would have frozen the redesigned comp's 27 block kinds
45
+ * (`Invoice Builder.dc.html` blockOrder:1114, custom:1266-1272) into a
46
+ * contract eighteen repos vendor, making every later block a contract release.
47
+ *
48
+ * A starter is a TEMPLATE PRESET, not a kind (O28(b), D54) — which is why
49
+ * `kinds()` stays at three for the invoices provider while the surface offers
50
+ * twelve starters over eight titles.
51
+ */
52
+ import { z } from 'zod';
53
+ /**
54
+ * The eight compiled locales, HYPHENATED — the spelling the add-ons repo
55
+ * already writes (`barcode-labels/src/i18n/strings.ts`, and the `LOCALES`
56
+ * array repeated in `host/src/app-neutral.test.ts:435`).
57
+ *
58
+ * **[DEP-33 — a departure from Appendix B, forced and minimal.]** Appendix B
59
+ * names this type `BuiltinLocaleId`. `@adminium/i18n` ALREADY exports a
60
+ * `BuiltinLocaleId` (`locales.ts:82`) and its members are the UNDERSCORE
61
+ * spellings — `en_US`, `ar_EG`. Two same-named unions with different members
62
+ * is not a nuisance, it is a data bug waiting in `apps/server`, which will
63
+ * import both the moment 34b wires the pipeline: `'en-US'` assigned where
64
+ * `'en_US'` is meant fails no compile and produces a missing translation at
65
+ * run time. So the contract's type is named for the contract. The MEMBERS are
66
+ * Appendix B's, unchanged.
67
+ */
68
+ export declare const DOCUMENT_LOCALE_IDS: readonly ["ar-EG", "cs-CZ", "da-DK", "de-DE", "en-US", "fr-FR", "zh-CN", "zh-TW"];
69
+ export type DocumentLocaleId = (typeof DOCUMENT_LOCALE_IDS)[number];
70
+ /**
71
+ * A string in every one of the eight locales. There is no fallback and no
72
+ * partial: a record missing one locale fails `describeDocumentRenderer`
73
+ * (0.3 trap 19), because the Studio profile editor renders these labels
74
+ * directly and a hole in one language becomes a raw slot id on somebody's
75
+ * screen. The server half of an add-on carries its own strings — the engine
76
+ * needs no bundle from it (34 D14).
77
+ */
78
+ export type LocalizedText = Readonly<Record<DocumentLocaleId, string>>;
79
+ export declare const localizedTextSchema: z.ZodObject<{
80
+ "ar-EG": z.ZodString;
81
+ "cs-CZ": z.ZodString;
82
+ "da-DK": z.ZodString;
83
+ "de-DE": z.ZodString;
84
+ "en-US": z.ZodString;
85
+ "fr-FR": z.ZodString;
86
+ "zh-CN": z.ZodString;
87
+ "zh-TW": z.ZodString;
88
+ }, z.core.$strict>;
89
+ /** What a kind may be rendered to. */
90
+ export declare const DOCUMENT_FORMATS: readonly ["html", "pdf"];
91
+ export type DocumentFormat = (typeof DOCUMENT_FORMATS)[number];
92
+ /** The paper a kind is drawn for. `receipt-80mm` is a till roll, not a sheet. */
93
+ export declare const DOCUMENT_PAPERS: readonly ["a4", "letter", "receipt-80mm"];
94
+ export type DocumentPaper = (typeof DOCUMENT_PAPERS)[number];
95
+ /**
96
+ * Which glyphs the kind's PDF writer can draw.
97
+ *
98
+ * `ascii` — 0x20..0x7E only (barcode-labels' scaffold: every byte is ASCII, so
99
+ * `String.length` is the byte length and the xref offsets are exact).
100
+ * `winansi` — the 224 drawable code points of WinAnsiEncoding, which is base-14
101
+ * Helvetica's repertoire: Latin-1 plus €, the smart quotes and the dashes.
102
+ * `all` — no refusal is possible; nothing claims it yet.
103
+ */
104
+ export declare const DOCUMENT_COVERAGES: readonly ["ascii", "winansi", "all"];
105
+ export type DocumentCoverage = (typeof DOCUMENT_COVERAGES)[number];
106
+ export interface DocumentKind {
107
+ /** `invoice` | `receipt` | `credit-note` | `label-sheet` | … */
108
+ id: string;
109
+ label: LocalizedText;
110
+ /** PER KIND. `label-sheet` is `['pdf']`; "html always" is not the law. */
111
+ formats: readonly DocumentFormat[];
112
+ paper: readonly DocumentPaper[];
113
+ /** The suite's `é ß ø €` assertion runs only where coverage includes them. */
114
+ coverage: DocumentCoverage;
115
+ }
116
+ export declare const documentKindSchema: z.ZodObject<{
117
+ id: z.ZodString;
118
+ label: z.ZodObject<{
119
+ "ar-EG": z.ZodString;
120
+ "cs-CZ": z.ZodString;
121
+ "da-DK": z.ZodString;
122
+ "de-DE": z.ZodString;
123
+ "en-US": z.ZodString;
124
+ "fr-FR": z.ZodString;
125
+ "zh-CN": z.ZodString;
126
+ "zh-TW": z.ZodString;
127
+ }, z.core.$strict>;
128
+ formats: z.ZodArray<z.ZodEnum<{
129
+ html: "html";
130
+ pdf: "pdf";
131
+ }>>;
132
+ paper: z.ZodArray<z.ZodEnum<{
133
+ a4: "a4";
134
+ letter: "letter";
135
+ "receipt-80mm": "receipt-80mm";
136
+ }>>;
137
+ coverage: z.ZodEnum<{
138
+ ascii: "ascii";
139
+ winansi: "winansi";
140
+ all: "all";
141
+ }>;
142
+ }, z.core.$strict>;
143
+ /** The value types a slot can carry. `money` is integer minor units; `percent` is basis points. */
144
+ export declare const OUTLINE_SLOT_TYPES: readonly ["text", "text[]", "date", "email", "money", "percent", "currency", "number", "collection"];
145
+ export type OutlineSlotType = (typeof OUTLINE_SLOT_TYPES)[number];
146
+ /**
147
+ * Where an unmapped slot's value comes from, if anywhere.
148
+ *
149
+ * `sequence` — the engine's CAS document number, minted after render (34 D11).
150
+ * `connection` — the connection's currency.
151
+ * `setting` — one of the add-on's own non-secret settings.
152
+ * `now` — `subject.now.iso`, never the provider's own clock.
153
+ */
154
+ export declare const OUTLINE_SLOT_DEFAULTS: readonly ["sequence", "connection", "setting", "now"];
155
+ export type OutlineSlotDefault = (typeof OUTLINE_SLOT_DEFAULTS)[number];
156
+ export interface OutlineSlot {
157
+ id: string;
158
+ /** The Studio mapping editor's row label — never a raw id on a screen. */
159
+ label: LocalizedText;
160
+ help?: LocalizedText;
161
+ type: OutlineSlotType;
162
+ required: boolean;
163
+ default?: OutlineSlotDefault;
164
+ /** For `collection` only — the columns of one row. Never nested twice. */
165
+ columns?: readonly OutlineSlot[];
166
+ }
167
+ /** One column of a `collection`. A column is never itself a collection. */
168
+ export declare const outlineLeafSlotSchema: z.ZodObject<{
169
+ id: z.ZodString;
170
+ label: z.ZodObject<{
171
+ "ar-EG": z.ZodString;
172
+ "cs-CZ": z.ZodString;
173
+ "da-DK": z.ZodString;
174
+ "de-DE": z.ZodString;
175
+ "en-US": z.ZodString;
176
+ "fr-FR": z.ZodString;
177
+ "zh-CN": z.ZodString;
178
+ "zh-TW": z.ZodString;
179
+ }, z.core.$strict>;
180
+ help: z.ZodOptional<z.ZodObject<{
181
+ "ar-EG": z.ZodString;
182
+ "cs-CZ": z.ZodString;
183
+ "da-DK": z.ZodString;
184
+ "de-DE": z.ZodString;
185
+ "en-US": z.ZodString;
186
+ "fr-FR": z.ZodString;
187
+ "zh-CN": z.ZodString;
188
+ "zh-TW": z.ZodString;
189
+ }, z.core.$strict>>;
190
+ type: z.ZodEnum<{
191
+ number: "number";
192
+ email: "email";
193
+ date: "date";
194
+ text: "text";
195
+ "text[]": "text[]";
196
+ money: "money";
197
+ percent: "percent";
198
+ currency: "currency";
199
+ collection: "collection";
200
+ }>;
201
+ required: z.ZodBoolean;
202
+ default: z.ZodOptional<z.ZodEnum<{
203
+ sequence: "sequence";
204
+ connection: "connection";
205
+ setting: "setting";
206
+ now: "now";
207
+ }>>;
208
+ }, z.core.$strict>;
209
+ /**
210
+ * The depth limit is in the SCHEMA, not in a comment.
211
+ *
212
+ * `OutlineSlot.columns` is typed `readonly OutlineSlot[]` (Appendix B), which
213
+ * would admit a collection of collections; nothing maps one, no renderer draws
214
+ * one, and the Studio mapping editor has no row for one. So the validator
215
+ * accepts exactly two levels and refuses the third — a provider that returns a
216
+ * nested collection fails `describeDocumentRenderer` with a parse error naming
217
+ * the slot, rather than passing here and rendering an empty table later.
218
+ */
219
+ export declare const outlineSlotSchema: z.ZodObject<{
220
+ columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
221
+ id: z.ZodString;
222
+ label: z.ZodObject<{
223
+ "ar-EG": z.ZodString;
224
+ "cs-CZ": z.ZodString;
225
+ "da-DK": z.ZodString;
226
+ "de-DE": z.ZodString;
227
+ "en-US": z.ZodString;
228
+ "fr-FR": z.ZodString;
229
+ "zh-CN": z.ZodString;
230
+ "zh-TW": z.ZodString;
231
+ }, z.core.$strict>;
232
+ help: z.ZodOptional<z.ZodObject<{
233
+ "ar-EG": z.ZodString;
234
+ "cs-CZ": z.ZodString;
235
+ "da-DK": z.ZodString;
236
+ "de-DE": z.ZodString;
237
+ "en-US": z.ZodString;
238
+ "fr-FR": z.ZodString;
239
+ "zh-CN": z.ZodString;
240
+ "zh-TW": z.ZodString;
241
+ }, z.core.$strict>>;
242
+ type: z.ZodEnum<{
243
+ number: "number";
244
+ email: "email";
245
+ date: "date";
246
+ text: "text";
247
+ "text[]": "text[]";
248
+ money: "money";
249
+ percent: "percent";
250
+ currency: "currency";
251
+ collection: "collection";
252
+ }>;
253
+ required: z.ZodBoolean;
254
+ default: z.ZodOptional<z.ZodEnum<{
255
+ sequence: "sequence";
256
+ connection: "connection";
257
+ setting: "setting";
258
+ now: "now";
259
+ }>>;
260
+ }, z.core.$strict>>>;
261
+ id: z.ZodString;
262
+ label: z.ZodObject<{
263
+ "ar-EG": z.ZodString;
264
+ "cs-CZ": z.ZodString;
265
+ "da-DK": z.ZodString;
266
+ "de-DE": z.ZodString;
267
+ "en-US": z.ZodString;
268
+ "fr-FR": z.ZodString;
269
+ "zh-CN": z.ZodString;
270
+ "zh-TW": z.ZodString;
271
+ }, z.core.$strict>;
272
+ help: z.ZodOptional<z.ZodObject<{
273
+ "ar-EG": z.ZodString;
274
+ "cs-CZ": z.ZodString;
275
+ "da-DK": z.ZodString;
276
+ "de-DE": z.ZodString;
277
+ "en-US": z.ZodString;
278
+ "fr-FR": z.ZodString;
279
+ "zh-CN": z.ZodString;
280
+ "zh-TW": z.ZodString;
281
+ }, z.core.$strict>>;
282
+ type: z.ZodEnum<{
283
+ number: "number";
284
+ email: "email";
285
+ date: "date";
286
+ text: "text";
287
+ "text[]": "text[]";
288
+ money: "money";
289
+ percent: "percent";
290
+ currency: "currency";
291
+ collection: "collection";
292
+ }>;
293
+ required: z.ZodBoolean;
294
+ default: z.ZodOptional<z.ZodEnum<{
295
+ sequence: "sequence";
296
+ connection: "connection";
297
+ setting: "setting";
298
+ now: "now";
299
+ }>>;
300
+ }, z.core.$strict>;
301
+ export interface DocumentOutline {
302
+ slots: readonly OutlineSlot[];
303
+ }
304
+ export declare const documentOutlineSchema: z.ZodObject<{
305
+ slots: z.ZodArray<z.ZodObject<{
306
+ columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
307
+ id: z.ZodString;
308
+ label: z.ZodObject<{
309
+ "ar-EG": z.ZodString;
310
+ "cs-CZ": z.ZodString;
311
+ "da-DK": z.ZodString;
312
+ "de-DE": z.ZodString;
313
+ "en-US": z.ZodString;
314
+ "fr-FR": z.ZodString;
315
+ "zh-CN": z.ZodString;
316
+ "zh-TW": z.ZodString;
317
+ }, z.core.$strict>;
318
+ help: z.ZodOptional<z.ZodObject<{
319
+ "ar-EG": z.ZodString;
320
+ "cs-CZ": z.ZodString;
321
+ "da-DK": z.ZodString;
322
+ "de-DE": z.ZodString;
323
+ "en-US": z.ZodString;
324
+ "fr-FR": z.ZodString;
325
+ "zh-CN": z.ZodString;
326
+ "zh-TW": z.ZodString;
327
+ }, z.core.$strict>>;
328
+ type: z.ZodEnum<{
329
+ number: "number";
330
+ email: "email";
331
+ date: "date";
332
+ text: "text";
333
+ "text[]": "text[]";
334
+ money: "money";
335
+ percent: "percent";
336
+ currency: "currency";
337
+ collection: "collection";
338
+ }>;
339
+ required: z.ZodBoolean;
340
+ default: z.ZodOptional<z.ZodEnum<{
341
+ sequence: "sequence";
342
+ connection: "connection";
343
+ setting: "setting";
344
+ now: "now";
345
+ }>>;
346
+ }, z.core.$strict>>>;
347
+ id: z.ZodString;
348
+ label: z.ZodObject<{
349
+ "ar-EG": z.ZodString;
350
+ "cs-CZ": z.ZodString;
351
+ "da-DK": z.ZodString;
352
+ "de-DE": z.ZodString;
353
+ "en-US": z.ZodString;
354
+ "fr-FR": z.ZodString;
355
+ "zh-CN": z.ZodString;
356
+ "zh-TW": z.ZodString;
357
+ }, z.core.$strict>;
358
+ help: z.ZodOptional<z.ZodObject<{
359
+ "ar-EG": z.ZodString;
360
+ "cs-CZ": z.ZodString;
361
+ "da-DK": z.ZodString;
362
+ "de-DE": z.ZodString;
363
+ "en-US": z.ZodString;
364
+ "fr-FR": z.ZodString;
365
+ "zh-CN": z.ZodString;
366
+ "zh-TW": z.ZodString;
367
+ }, z.core.$strict>>;
368
+ type: z.ZodEnum<{
369
+ number: "number";
370
+ email: "email";
371
+ date: "date";
372
+ text: "text";
373
+ "text[]": "text[]";
374
+ money: "money";
375
+ percent: "percent";
376
+ currency: "currency";
377
+ collection: "collection";
378
+ }>;
379
+ required: z.ZodBoolean;
380
+ default: z.ZodOptional<z.ZodEnum<{
381
+ sequence: "sequence";
382
+ connection: "connection";
383
+ setting: "setting";
384
+ now: "now";
385
+ }>>;
386
+ }, z.core.$strict>>;
387
+ }, z.core.$strict>;
388
+ /**
389
+ * A soft reference to the record a document was issued for.
390
+ *
391
+ * Structurally the same object as `@adminium/meta`'s `recordRefSchema`
392
+ * (`json-payloads.ts:17-25`), which is the AUTHORITY for the shape; it is
393
+ * restated here because this package has no `node:` and no meta dependency by
394
+ * design (01 §3). A file that imports both should alias one — they are two
395
+ * declarations of one shape, not two shapes.
396
+ */
397
+ export interface RecordRef {
398
+ connectionId: string;
399
+ /** Qualified source name, e.g. `public.orders`. */
400
+ table: string;
401
+ /** Full PK map — composite keys included. */
402
+ pk: Readonly<Record<string, unknown>>;
403
+ /** Display snapshot taken at write time. */
404
+ label: string;
405
+ }
406
+ /**
407
+ * What a PUBLIC caller may send (34 D15): values, and nothing that decides
408
+ * anything. The server stamps `business`, `now`, `currency`, `entity: null`
409
+ * and `number: null` itself — a request that carries one of them is refused
410
+ * `INVALID_REQUEST` rather than quietly overwritten, so a customer cannot
411
+ * post a document that claims to come from a different business or to have
412
+ * been issued last year.
413
+ *
414
+ * `customerEmail` is stored on the row and NEVER sent unattended: delivery
415
+ * starts `pending-review` and a person presses send.
416
+ */
417
+ export interface PublicDocumentRequest {
418
+ kind: string;
419
+ locale?: string;
420
+ /** Scalar slots by id. Money arrives as a decimal string, coerced server-side. */
421
+ fields: Readonly<Record<string, unknown>>;
422
+ collections: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>;
423
+ customerEmail?: string;
424
+ }
425
+ export declare const publicDocumentRequestSchema: z.ZodObject<{
426
+ kind: z.ZodString;
427
+ locale: z.ZodOptional<z.ZodString>;
428
+ fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
429
+ collections: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
430
+ customerEmail: z.ZodOptional<z.ZodString>;
431
+ }, z.core.$strict>;
432
+ export interface DocumentSubject {
433
+ /** The only clock the provider may read. */
434
+ now: {
435
+ iso: string;
436
+ timezone: string;
437
+ };
438
+ locale: string;
439
+ /** ISO-4217. */
440
+ currency: string;
441
+ business: {
442
+ name: string;
443
+ lines: readonly string[];
444
+ logoDataUrl?: string;
445
+ };
446
+ /** `null` for request-shaped intents (34 D15). */
447
+ entity: RecordRef | null;
448
+ /** `null` until minted; a re-render carries the number it already has. */
449
+ number: string | null;
450
+ /** Scalar slots by id. Money is INTEGER MINOR UNITS; percent is BASIS POINTS. */
451
+ fields: Readonly<Record<string, unknown>>;
452
+ collections: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>;
453
+ }
454
+ export declare const documentSubjectSchema: z.ZodObject<{
455
+ now: z.ZodObject<{
456
+ iso: z.ZodString;
457
+ timezone: z.ZodString;
458
+ }, z.core.$strict>;
459
+ locale: z.ZodString;
460
+ currency: z.ZodString;
461
+ business: z.ZodObject<{
462
+ name: z.ZodString;
463
+ lines: z.ZodArray<z.ZodString>;
464
+ logoDataUrl: z.ZodOptional<z.ZodString>;
465
+ }, z.core.$strict>;
466
+ entity: z.ZodNullable<z.ZodObject<{
467
+ connectionId: z.ZodString;
468
+ table: z.ZodString;
469
+ pk: z.ZodRecord<z.ZodString, z.ZodUnknown>;
470
+ label: z.ZodString;
471
+ }, z.core.$strict>>;
472
+ number: z.ZodNullable<z.ZodString>;
473
+ fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
474
+ collections: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
475
+ }, z.core.$strict>;
476
+ export interface RenderInput {
477
+ kind: string;
478
+ subject: DocumentSubject;
479
+ formats: readonly DocumentFormat[];
480
+ paper: DocumentPaper;
481
+ /** The add-on's own non-secret values. A secret never reaches a renderer. */
482
+ settings: Readonly<Record<string, unknown>>;
483
+ /**
484
+ * The authored composition, when there is one — the redesigned comp makes a
485
+ * document's BODY per-record data (`blockOrder`, the 18 `*Show` flags, the
486
+ * `custom[]` entries and ~70 authored fields), and none of that can be drawn
487
+ * from `subject`, which is a slot map.
488
+ *
489
+ * OPAQUE BY RULING (O28(a2) → D54): the provider owns the schema and
490
+ * validates it. Absent for a purely mapped render.
491
+ */
492
+ body?: Readonly<Record<string, unknown>>;
493
+ }
494
+ export interface RenderedDocument {
495
+ format: DocumentFormat;
496
+ filename: string;
497
+ mediaType: string;
498
+ /** The document itself. NOT a `FileRef` — that one's `bytes` is a count. */
499
+ bytes: Uint8Array;
500
+ locale: string;
501
+ warnings: readonly string[];
502
+ }
503
+ export declare const renderedDocumentSchema: z.ZodObject<{
504
+ format: z.ZodEnum<{
505
+ html: "html";
506
+ pdf: "pdf";
507
+ }>;
508
+ filename: z.ZodString;
509
+ mediaType: z.ZodString;
510
+ bytes: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
511
+ locale: z.ZodString;
512
+ warnings: z.ZodArray<z.ZodString>;
513
+ }, z.core.$strict>;
514
+ /**
515
+ * A refusal is DATA, returned — never thrown, and never a silent partial
516
+ * result. `shipping-carrier`'s `CarrierError` is a class because a carrier's
517
+ * own words have to reach the screen verbatim; here every refusal is one of
518
+ * four things the engine can act on, so a union of codes is the honest shape.
519
+ */
520
+ export declare const DOCUMENT_ERROR_CODES: readonly ["LATIN_ONLY", "UNSUPPORTED_KIND", "MISSING_SLOT", "INVALID_SUBJECT"];
521
+ export type DocumentErrorCode = (typeof DOCUMENT_ERROR_CODES)[number];
522
+ export interface DocumentError {
523
+ code: DocumentErrorCode;
524
+ detail?: string;
525
+ /** `LATIN_ONLY` only: the glyphs that could not be drawn. Never empty when set. */
526
+ dropped?: readonly string[];
527
+ }
528
+ export declare const documentErrorSchema: z.ZodObject<{
529
+ code: z.ZodEnum<{
530
+ LATIN_ONLY: "LATIN_ONLY";
531
+ UNSUPPORTED_KIND: "UNSUPPORTED_KIND";
532
+ MISSING_SLOT: "MISSING_SLOT";
533
+ INVALID_SUBJECT: "INVALID_SUBJECT";
534
+ }>;
535
+ detail: z.ZodOptional<z.ZodString>;
536
+ dropped: z.ZodOptional<z.ZodArray<z.ZodString>>;
537
+ }, z.core.$strict>;
538
+ /** Narrows `render`'s union without a `code in x` incantation at every call site. */
539
+ export declare function isDocumentError(value: readonly RenderedDocument[] | DocumentError): value is DocumentError;
540
+ export interface DocumentRenderer {
541
+ /** The add-on's key — how a profile names the provider it wants. */
542
+ readonly key: string;
543
+ kinds(): readonly DocumentKind[];
544
+ describe(kind: string): DocumentOutline;
545
+ render(input: RenderInput): Promise<readonly RenderedDocument[] | DocumentError>;
546
+ }
547
+ //# sourceMappingURL=document-render.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"document-render.d.ts","sourceRoot":"","sources":["../src/document-render.ts"],"names":[],"mappings":"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"}