ezship 0.1.11 → 0.1.13

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/types.d.mts ADDED
@@ -0,0 +1,879 @@
1
+ // The ezship HTTP API's request and response shapes: the single description that the platform (which serves
2
+ // them, typed through `reply()` in platform.ts) and the studio (which calls them) import, and the shapes the
3
+ // contract's Workspace (commands.d.mts) returns. Which route carries which shape is ROUTES in commands.mjs.
4
+ // Vocabulary per CONTEXT.md: Host, Instance, Site, Builder, Admin, End User, Member.
5
+
6
+ export type { Conflict, Declaration, LiveSchema, Plan, PlanSummary, Table } from "./schema.d.mts";
7
+
8
+ /**
9
+ * A Builder's role in one Instance (docs/adr/0025). `limited` edits and deploys Sites and invites Members;
10
+ * `builder` additionally pushes the Global Workspace and creates Sites; `admin` additionally archives and
11
+ * restricts Sites, manages Builders and roles, and changes the Instance's settings and assets.
12
+ */
13
+ export type BuilderRole = "admin" | "builder" | "limited";
14
+
15
+ /** The shared files' version: bumped once per push, recorded by `ez pull` and `ez push` as the baseline. */
16
+ export type Version = {
17
+ n: number;
18
+ by: string | null;
19
+ at: number | null;
20
+ /** The Push's message (docs/adr/0093), where the Version comes from a retained Version: versions, pull --version, push. */
21
+ message?: string | null;
22
+ /** `ez versions` of a Site (docs/adr/0141): when a deploy last shipped this Version, null when none has. */
23
+ deployedAt?: number | null;
24
+ /** `ez versions` of a Site: this is the Version the Site's latest deploy shipped, what Members see now. */
25
+ live?: boolean;
26
+ };
27
+
28
+ /** Credential-free Instance connection information, served at /.well-known/ezship (ADR 0026). */
29
+ export type InstanceDiscovery = {
30
+ version: 1;
31
+ uid: string;
32
+ instance: string;
33
+ name: string;
34
+ app: string;
35
+ api: string;
36
+ };
37
+
38
+ /** Email-verified, demo-Host-only bootstrap; never a general lifecycle API. */
39
+ export type SignupInput = { email: string; name: string; source: "cli" | "plugin" | "web" };
40
+ export type SignupChallenge = { receipt: string; expiresAt: number };
41
+ /** `studio` is the trial's Studio address; the verification email's button opens it signed in (ADR 0064). */
42
+ export type SignupResult = { connection: InstanceDiscovery; token: string; studio: string };
43
+ /** Credential-free facts about an active signup trial on its own API origin (ADR 0063). */
44
+ export type SignupTrialStatus = { uid: string; instance: string; expiresAt: number };
45
+
46
+ /** An Instance's settings (the `instances` row). One Instance == one customer == the unit of tenancy. */
47
+ export type Instance = {
48
+ id: string;
49
+ uid: string;
50
+ appOrigin: string;
51
+ apiOrigin: string;
52
+ name: string;
53
+ updatedAt: number;
54
+ };
55
+
56
+ /** The Instance plus the caller's role in it (`ez instance`, Workspace.instanceStatus). */
57
+ export type InstanceInfo = Instance & { role: BuilderRole };
58
+
59
+ /** A Site as listed within an Instance (`ez site ls`, and inside InstanceSummary). */
60
+ export type SiteSummary = { id: string; name: string; restricted: boolean };
61
+
62
+ /** An Instance as listed for the signed-in Builder (GET /api/instances), with the Sites they may open. */
63
+ export type InstanceSummary = {
64
+ id: string;
65
+ name: string;
66
+ role: BuilderRole;
67
+ sites: SiteSummary[];
68
+ };
69
+
70
+ /** A Site's settings and timestamps (the `sites` row). `instance` + `id` is its key. */
71
+ export type Site = {
72
+ instance: string;
73
+ id: string;
74
+ name: string;
75
+ restricted: boolean;
76
+ updatedAt: number;
77
+ deployedAt: number | null;
78
+ };
79
+
80
+ /** The Site row plus the shared files' version, its app URL and the caller's role (`ez config`, Workspace.remoteStatus). */
81
+ export type WorkspaceInfo = Site & { version: Version; appUrl: string | null; role: BuilderRole };
82
+
83
+ /**
84
+ * What a push did (Workspace.pushAll). A Global push also lists its Live changes (docs/adr/0096), which took
85
+ * effect for every deployed Site at once; everything else reaches a Site at its next Preview or Deploy.
86
+ */
87
+ export type PushResult = {
88
+ version: Version;
89
+ written: string[];
90
+ deleted: string[];
91
+ live?: LiveChange[];
92
+ /** What changed access rules do to Members' rows (docs/adr/0098); present when a READ or WRITE changed. */
93
+ report?: AccessReport[];
94
+ /** What the pushed guards would have done to the last 7 days of writes (docs/adr/0099). */
95
+ rulesReport?: RulesReport[];
96
+ /** `ez global push --dry-run`: checked and reported, nothing saved; `version` is the current one. */
97
+ dryRun?: true;
98
+ };
99
+
100
+ /**
101
+ * One guard's replay (docs/adr/0099): of `replayed` recent writes to `table`, how many it would have
102
+ * refused, by whom (History actor ids), with a few of its messages.
103
+ */
104
+ export type RulesReport = {
105
+ table: string;
106
+ replayed: number;
107
+ refused: number;
108
+ by: Record<string, number>;
109
+ messages: string[];
110
+ };
111
+
112
+ /**
113
+ * One changed rule's effect (docs/adr/0098): per Member, how many rows they may read (or write) after the
114
+ * Push, and how many they gain and lose. Only Members whose rows change are listed; `sampled` of the
115
+ * Instance's `total` active Members were compared (at most 200).
116
+ */
117
+ export type AccessReport = {
118
+ table: string;
119
+ op: "read" | "write";
120
+ members: { email: string; after: number; gained: number; lost: number }[];
121
+ sampled: number;
122
+ total: number;
123
+ };
124
+
125
+ /**
126
+ * One Live change of a Global push (docs/adr/0096). A default (docs/adr/0097) is printed as declared, null
127
+ * for none; `nulls` counts the existing rows a new default does not fill.
128
+ */
129
+ export type LiveChange =
130
+ | {
131
+ kind: "default";
132
+ table: string;
133
+ column: string;
134
+ from: string | null;
135
+ to: string | null;
136
+ nulls?: number;
137
+ }
138
+ | { kind: "access"; table: string; op: "read" | "write"; from: string; to: string }
139
+ | { kind: "scope"; from: string | null; to: string | null }
140
+ /** The GROUP statements (docs/adr/0101), normalized; null for none. */
141
+ | { kind: "groups"; from: string | null; to: string | null }
142
+ /** Table rules (docs/adr/0099): the Tables whose rules this Push compiled, empty when it removed them all. */
143
+ | { kind: "rules"; tables: string[] }
144
+ /** Workflows (docs/adr/0103): the Tables whose workflow this Push added, changed or removed. */
145
+ | { kind: "workflows"; tables: string[] }
146
+ /** Schedules (ADR 0136): the schedules.json entries this Push added, changed or removed. */
147
+ | { kind: "schedules"; names: string[] }
148
+ /** Jobs (ADR 0136): the jobs/ files this Push added, changed or removed. */
149
+ | { kind: "jobs"; names: string[] }
150
+ /**
151
+ * An integrity constraint added or removed (docs/adr/0109): SINGLETON, EXACTLY ONE OF (its columns) or
152
+ * ON DELETE RESTRICT (the referencing column, of `table`).
153
+ */
154
+ | IntegrityChange
155
+ | { kind: "session" };
156
+ export type IntegrityChange = {
157
+ kind: "integrity";
158
+ table: string;
159
+ constraint: "singleton" | "exactly-one" | "restrict";
160
+ columns?: string[];
161
+ column?: string;
162
+ added: boolean;
163
+ };
164
+
165
+ /** What a deploy did (Workspace.deploy), including what it did to the App Database (docs/adr/0007). */
166
+ export type DeployResult = {
167
+ deployedAt: number;
168
+ files: string[];
169
+ appUrl: string | null;
170
+ schema: { created: string[]; added: string[]; indexed: string[] };
171
+ /** The Global Workspace's Version compiled into this deploy (0 when it has never been pushed). */
172
+ global: number;
173
+ /** What deployed but will not work yet, such as an Integration the Instance has not set (ADR 0092). */
174
+ warnings?: string[];
175
+ };
176
+
177
+ // ---- hosted Previews (docs/adr/0013) ----
178
+
179
+ /** Where a Preview's files came from. */
180
+ export type PreviewSource = { kind: "upload" } | { kind: "version"; n: number };
181
+ /**
182
+ * PUT .../previews/:name: a Working Copy, or a retained Version's number; `seq` orders uploads (Date.now() in both
183
+ * clients). `global` is a Working Copy of the Global Workspace to build in instead of the pushed one (the studio
184
+ * sends its own so unpushed UI edits show in the Preview); absent, the pushed Global Workspace.
185
+ * Schema definitions must match the published global schema; uploads never publish schema additions.
186
+ */
187
+ export type PreviewInput = {
188
+ seq: number;
189
+ files?: Record<string, string>;
190
+ version?: number;
191
+ global?: Record<string, string>;
192
+ };
193
+ /** One Preview as its owner lists it. `url` is the hosted address; `diagnostics` are the last build's. */
194
+ export type PreviewRow = {
195
+ name: string;
196
+ url: string;
197
+ source: PreviewSource;
198
+ status: "ok" | "failed";
199
+ seq: number;
200
+ diagnostics: Diagnostic[];
201
+ /** The pushed Global Workspace's Version at build time (0 when never pushed); an upload may have carried its own. */
202
+ global: number;
203
+ createdAt: number;
204
+ builtAt: number | null;
205
+ activeAt: number;
206
+ };
207
+ /**
208
+ * Another Builder's Preview of this Site, as `ez preview ls --others` lists it (docs/adr/0141): who holds it
209
+ * and when it was last uploaded to or opened, never its URL or diagnostics, which stay its owner's.
210
+ */
211
+ export type OtherPreview = {
212
+ name: string;
213
+ /** The owner's display name, falling back to their email, as a Version's `by`. */
214
+ by: string;
215
+ source: PreviewSource;
216
+ status: "ok" | "failed";
217
+ activeAt: number;
218
+ };
219
+ /** What an upload did: the Preview, plus what its schema did to the App Database. */
220
+ export type PreviewResult = PreviewRow & { schema: DeployResult["schema"] };
221
+
222
+ /**
223
+ * `ez link` (docs/adr/0059): an address that opens the Site's app, or one of the caller's Previews, signed in
224
+ * as the caller's own Member identity. The token is in the fragment; it works once, until `expiresAt`.
225
+ */
226
+ export type AppLink = { url: string; expiresAt: number };
227
+
228
+ /**
229
+ * `ez support` (docs/adr/0080): a Builder's request to the Host's Developers. `site` is the Site the client
230
+ * was bound to, or null; `diagnostics` are what the Host recorded with it (its build, the client's contract,
231
+ * the opening request's id); `resolution` is the Developer's note on closing, if any.
232
+ */
233
+ export type SupportRequest = {
234
+ id: number;
235
+ instance: string;
236
+ site: string | null;
237
+ subject: string;
238
+ body: string;
239
+ status: "open" | "closed";
240
+ openedBy: { id: string; email: string; name: string | null };
241
+ openedAt: number;
242
+ closedAt: number | null;
243
+ resolution: string | null;
244
+ diagnostics: { build: string | null; contract: string | null; requestId: string | null };
245
+ };
246
+
247
+ /**
248
+ * Integrations (docs/adr/0092, 0094, 0138, 0140): an Instance's named external service. Nobody reads a
249
+ * credential back: the wire carries its type, its header or parameter name and its last four characters
250
+ * (`hint`, empty for a value under 8 characters).
251
+ */
252
+ export type IntegrationCredentialInfo =
253
+ | { type: "header"; name: string; hint: string }
254
+ | { type: "query"; param: string; hint: string }
255
+ | { type: "basic"; user: string; hint: string }
256
+ | IntegrationOAuthInfo;
257
+ /** How an OAuth client gets its token (docs/adr/0140, a draft: only the configuration is built). */
258
+ export type OAuthGrant = "client-credentials" | "password" | "authorization-code";
259
+ /** How the client authenticates at the token endpoint: HTTP Basic, or its id and secret in the form. */
260
+ export type OAuthClientAuth = "basic" | "post";
261
+ /**
262
+ * Whether the Host holds a grant for a binding. Until ADR 0140's flows are built every OAuth binding is
263
+ * `not connected` and its calls are refused `grant`.
264
+ */
265
+ export type OAuthStatus = "not connected" | "connected" | "needs-reconnect";
266
+ /** An OAuth credential as the list shows it: its configuration, the client secret's hint, its status. */
267
+ export type IntegrationOAuthInfo = {
268
+ type: "oauth";
269
+ grant: OAuthGrant;
270
+ /** The preset it was set from (`OAUTH_PRESETS`), or null for one set from flags. */
271
+ preset: string | null;
272
+ clientId: string;
273
+ /** The client secret's hint. */
274
+ hint: string;
275
+ tokenUrl: string;
276
+ authorizeUrl: string | null;
277
+ revokeUrl: string | null;
278
+ scopes: string[];
279
+ clientAuth: OAuthClientAuth;
280
+ /** The account a `password` grant signs in as. */
281
+ user?: string;
282
+ status: OAuthStatus;
283
+ /** The grant's connection values (a QuickBooks Online realmId), `{}` until connected. */
284
+ connection: Record<string, string>;
285
+ };
286
+ /**
287
+ * A header or query parameter the Host adds to every request a binding makes (docs/adr/0138). Code can
288
+ * neither set nor override it. A plain one is shown in full; a secret one only by its hint.
289
+ */
290
+ export type IntegrationValueInfo =
291
+ | { place: "header" | "query"; name: string; secret: false; value: string }
292
+ | { place: "header" | "query"; name: string; secret: true; hint: string };
293
+ /** Where requests go: an origin, optionally the credential the Host adds to each, and its values. */
294
+ export type IntegrationBinding = {
295
+ origin: string;
296
+ credential: IntegrationCredentialInfo | null;
297
+ values: IntegrationValueInfo[];
298
+ };
299
+ export type Integration = {
300
+ name: string;
301
+ kind: "http";
302
+ /** The Sites whose code may call it. */
303
+ sites: "all" | string[];
304
+ timeoutSeconds: number;
305
+ production: IntegrationBinding;
306
+ /** What a Preview calls: its own binding, the production one, or nothing (null, the default). */
307
+ preview: IntegrationBinding | "production" | null;
308
+ /** Sites whose deployed artifact records the name. */
309
+ usedBy: string[];
310
+ updatedAt: number;
311
+ updatedBy: string;
312
+ /**
313
+ * What `ez integration set` or `preview` removed: the secret values of a binding whose origin changed
314
+ * (docs/adr/0138). Only on the answer to that command.
315
+ */
316
+ removedValues?: string[];
317
+ };
318
+ /** A credential as an Admin sends it, once; it is sealed on arrival and never answered. */
319
+ export type IntegrationCredential =
320
+ | { type: "header"; name: string; value: string }
321
+ | { type: "query"; param: string; value: string }
322
+ | { type: "basic"; user: string; password: string }
323
+ | {
324
+ type: "oauth";
325
+ grant: OAuthGrant;
326
+ preset?: string | null;
327
+ clientId: string;
328
+ clientSecret: string;
329
+ tokenUrl: string;
330
+ authorizeUrl?: string | null;
331
+ revokeUrl?: string | null;
332
+ scopes?: string[];
333
+ clientAuth?: OAuthClientAuth;
334
+ /** The `password` grant's account. */
335
+ user?: string;
336
+ password?: string;
337
+ };
338
+ /** `ez integration set`: the production binding, and the Sites and timeout when given (else kept). */
339
+ export type IntegrationInput = {
340
+ kind: "http";
341
+ origin: string;
342
+ credential: IntegrationCredential | null;
343
+ sites?: "all" | string[];
344
+ timeoutSeconds?: number;
345
+ };
346
+ /** `ez integration value`: one header or parameter on the production binding or the Preview's own. */
347
+ export type IntegrationValueInput = {
348
+ binding: "production" | "preview";
349
+ place: "header" | "query";
350
+ name: string;
351
+ secret: boolean;
352
+ value: string;
353
+ };
354
+ /** `ez integration value ... --remove`. */
355
+ export type IntegrationValueKey = {
356
+ binding: "production" | "preview";
357
+ place: "header" | "query";
358
+ name: string;
359
+ };
360
+ /** `ez integration preview`. */
361
+ export type IntegrationPreviewInput =
362
+ | { origin: string; credential: IntegrationCredential | null }
363
+ | { production: true }
364
+ | { none: true };
365
+ /** ADR 0092's refusal categories for an Integration call. */
366
+ export type IntegrationRefusal =
367
+ | "address"
368
+ | "origin"
369
+ | "ordering"
370
+ | "limit"
371
+ | "timeout"
372
+ | "size"
373
+ | "binary"
374
+ | "unrecorded"
375
+ | "site"
376
+ | "previews"
377
+ | "reflected"
378
+ | "grant";
379
+ /** One recorded call (`ez integration calls`): never a path, query, header value or body. */
380
+ export type IntegrationCall = {
381
+ at: number;
382
+ site: string;
383
+ binding: "production" | "preview";
384
+ /** The function, job or listener, or `test`. */
385
+ entry: string;
386
+ requestId: string;
387
+ status?: number;
388
+ ms: number;
389
+ refused?: IntegrationRefusal;
390
+ };
391
+ /** What server code passes to `request(path, options)`: at most one of `json`, `form` and `body`. */
392
+ export type IntegrationRequestOptions = {
393
+ method?: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
394
+ query?: Record<string, string>;
395
+ headers?: Record<string, string>;
396
+ json?: unknown;
397
+ form?: Record<string, string>;
398
+ body?: string;
399
+ };
400
+ /** A service's answer as it crosses the wire; server code also gets `json()`. */
401
+ export type IntegrationResponse = {
402
+ status: number;
403
+ ok: boolean;
404
+ headers: Record<string, string>;
405
+ text: string;
406
+ };
407
+ /** `ez integration test`. */
408
+ export type IntegrationTest = { path: string; method?: string; preview?: boolean };
409
+
410
+ /**
411
+ * A Builder as listed for an Instance (`ez builders`). `role` is their role in *that* Instance; `lastSignInAt`
412
+ * is null until they first sign in anywhere (an unclaimed invite), and `invitedAt` is when they were last
413
+ * invited anywhere: together they say whether the invite is still claimable (`inviteStatus` in the contract,
414
+ * docs/adr/0025). `protected` marks a PROTECTED_ADMINS address.
415
+ */
416
+ export type BuilderRow = {
417
+ id: string;
418
+ email: string;
419
+ name: string | null;
420
+ role: BuilderRole;
421
+ createdAt: number | null;
422
+ lastSignInAt: number | null;
423
+ invitedAt: number | null;
424
+ protected: boolean;
425
+ };
426
+
427
+ /** An End User's membership in an Instance (`ez users`). `lastSignInAt` and `invitedAt` as on BuilderRow. */
428
+ export type MemberRow = {
429
+ id: string;
430
+ email: string;
431
+ name: string;
432
+ role: string;
433
+ status: "active" | "blocked";
434
+ memberSince: number;
435
+ lastSignInAt: number | null;
436
+ invitedAt: number | null;
437
+ /** The Member's groups on the roster (docs/adr/0098), sorted. */
438
+ groups: string[];
439
+ };
440
+
441
+ /** Someone on a Restricted Site's allow-list. */
442
+ export type PersonRow = { id: string; email: string; name: string | null };
443
+
444
+ /** Who may open a Site (`ez site access`): the restricted flag and both allow-lists (empty when unrestricted). */
445
+ /** Who may open a Restricted Site: its Builders, its Members, and the Members of its groups (docs/adr/0101). */
446
+ export type SiteAccess = {
447
+ restricted: boolean;
448
+ builders: PersonRow[];
449
+ members: PersonRow[];
450
+ groups: string[];
451
+ };
452
+
453
+ /** Who did something in the audit trail. */
454
+ export type AuditActor = { id: string; email: string; name: string | null; via: string };
455
+ /** One row of an Instance's audit trail (`ez audit`). */
456
+ export type AuditEvent = {
457
+ id: number;
458
+ at: number;
459
+ actor: AuditActor;
460
+ kind: string;
461
+ site: string | null;
462
+ summary: string;
463
+ details: Record<string, unknown>;
464
+ };
465
+ /** The query behind `ez audit`'s flags. */
466
+ export type AuditFilter = { site?: string; kind?: string; before?: number; limit?: number };
467
+
468
+ /** A CLI token as listed (GET /api/tokens); the token itself is only returned once, at creation. */
469
+ export type TokenRow = {
470
+ id: string;
471
+ name: string;
472
+ prefix: string;
473
+ createdAt: number;
474
+ lastUsedAt: number | null;
475
+ expiresAt: number;
476
+ };
477
+
478
+ /** The signed-in Builder (GET /api/me). Roles are per Instance; see InstanceSummary. */
479
+ export type Me = {
480
+ /** Present on an Instance API; absent on the operator API. */
481
+ connection?: InstanceDiscovery;
482
+ id: string;
483
+ email: string;
484
+ name: string | null;
485
+ via: "session" | "token";
486
+ /** A PROTECTED_ADMINS address on this Host: may create and archive Instances. */
487
+ developer: boolean;
488
+ };
489
+
490
+ /** One entry per Table in the Instance's App Database (`ez db tables`). */
491
+ export type TableInfo = {
492
+ name: string;
493
+ /** column -> description as declared ("TEXT NOT NULL REFERENCES people"), or the storage type if nobody declares it */
494
+ columns: Record<string, string>;
495
+ indexes: string[][];
496
+ /** the unique indexes' column lists (docs/adr/0046); a sequence column has one */
497
+ unique?: string[][];
498
+ rows: number;
499
+ /** the Sites of this Instance whose Declaration includes this table */
500
+ sites: string[];
501
+ /** the Table this is the History of (docs/adr/0040), or null for a Table */
502
+ history: string | null;
503
+ };
504
+ /** `ez db sql`: rows for a read (capped, `truncated` says so), changed-row count for a write. */
505
+ export type SqlResult =
506
+ | { rows: Record<string, unknown>[]; truncated: boolean }
507
+ | { changed: number };
508
+ /** `ez db redact` (docs/adr/0106): declared columns of a Table to blank in its rows and their History. */
509
+ export type RedactInput = {
510
+ table: string;
511
+ columns: string[];
512
+ /**
513
+ * Which rows: their ids (deleted rows' History too), a filter on the current rows (the page query
514
+ * language's `where`), or every row the Table or its History holds.
515
+ */
516
+ rows: string[] | { where: Record<string, unknown> } | "all";
517
+ };
518
+ /** Current rows changed, and History rows blanked. */
519
+ export type RedactResult = { changed: number; history: number };
520
+
521
+ /** An Instance asset (`ez asset ls`, docs/adr/0014): a name, an immutable object, a frozen URL. */
522
+ export type AssetRow = {
523
+ id: string;
524
+ name: string;
525
+ contentType: string;
526
+ size: number;
527
+ status: "pending" | "ready";
528
+ createdBy: string | null;
529
+ createdAt: number;
530
+ /** Site-relative: `_ez/files/<name>` under any Site's prefix. */
531
+ url: string;
532
+ };
533
+ /**
534
+ * An App Attachment (docs/adr/0047): a file on one FILE column of one row. `row` is null until a row write
535
+ * binds it. `url` is Site-relative: `_ez/attachments/<id>` under any Site's prefix.
536
+ */
537
+ export type AttachmentRow = {
538
+ id: string;
539
+ table: string;
540
+ column: string;
541
+ row: string | null;
542
+ filename: string;
543
+ contentType: string;
544
+ size: number;
545
+ status: "pending" | "ready";
546
+ createdBy: string;
547
+ createdAt: number;
548
+ url: string;
549
+ };
550
+ /** What `ez db attach` asks for before sending the bytes: the existing row and the FILE column. */
551
+ export type AttachmentRequest = {
552
+ table: string;
553
+ row: string;
554
+ column: string;
555
+ filename: string;
556
+ size: number;
557
+ };
558
+ /** `ez db attachment`: the record plus the absolute bytes URL the adapter fetches with its credential. */
559
+ export type AttachmentInfo = AttachmentRow & { download: string };
560
+ /** What `ez asset add` asks for before sending the bytes. */
561
+ export type UploadRequest = { name: string; size: number; contentType: string };
562
+ /** The platform's answer: where the bytes go. `url` is absolute; the adapter adds its own credential. */
563
+ export type UploadTicket = {
564
+ id: string;
565
+ upload: { method: "PUT"; url: string; headers: Record<string, string> };
566
+ };
567
+
568
+ // ---- the Builder's wire (docs/adr/0012) ----
569
+
570
+ import type { Diagnostic } from "./commands.d.mts";
571
+ export type { Diagnostic };
572
+
573
+ /** POST /build on the Builder: a working copy in. `global` is the Global Workspace's files (plan 6). */
574
+ export type BuildInput = {
575
+ files: Record<string, string>;
576
+ global?: Record<string, string>;
577
+ /** `types` stops after the Rules and the type check: a Global check's look at each Site (docs/adr/0078).
578
+ * `format` formats the `.ts`/`.tsx` files and answers only the changed ones as `files` (docs/adr/0089).
579
+ * `rules` checks a Global Working Copy with `files` as a stand-in Site and answers its Table rules
580
+ * artifact (docs/adr/0099) as `files[RULES_ARTIFACT]`. */
581
+ mode: "check" | "build" | "types" | "format" | "rules";
582
+ title?: string;
583
+ /** A Preview build: stamps source locations for the Studio's inspector (docs/adr/0068). */
584
+ preview?: boolean;
585
+ };
586
+ export type BuildManifest = { entry: "index.html"; files: string[] };
587
+ /** Private build output; never served as a browser asset. */
588
+ export type FunctionArtifact = {
589
+ id: string;
590
+ names: string[];
591
+ /**
592
+ * The functions whose options say `{ api: true }` (docs/adr/0119): the only ones an API Key may call. The
593
+ * artifact's `__api` entry describes their inputs.
594
+ */
595
+ api?: string[];
596
+ /**
597
+ * Scheduled jobs (ADRs 0076, 0136), reached only by a run: an invocation whose context carries `run`. Only
598
+ * the Instance's job artifact, compiled at Global Push, has them.
599
+ */
600
+ jobs?: string[];
601
+ /**
602
+ * The Integration names each entry's code can reach (ADR 0092), following its imports of sibling
603
+ * functions; the Host refuses any other name, and Deploy and Preview check the Integrations' Sites.
604
+ */
605
+ /** Listeners (docs/adr/0092), reached only by an event: an invocation whose context carries `event`. */
606
+ listeners?: string[];
607
+ integrations?: {
608
+ functions: Record<string, string[]>;
609
+ jobs: Record<string, string[]>;
610
+ listeners: Record<string, string[]>;
611
+ };
612
+ code: string;
613
+ /**
614
+ * A rules artifact's (docs/adr/0099, 0103) code per name: a Table's rules or `workflow:<table>`, so a call
615
+ * evaluates that alone. `code` holds them all, and answers any name without a part.
616
+ */
617
+ parts?: Record<string, string>;
618
+ };
619
+ export type FunctionResult = { result: unknown; artifact: string };
620
+ /**
621
+ * One listeners.json entry (docs/adr/0092): `listeners/<name>.ts`, its events' source and how a delivery is
622
+ * verified. `header` and `idHeader` are the `token` scheme's.
623
+ */
624
+ export type ListenerEntry = {
625
+ name: string;
626
+ source: "webhook";
627
+ scheme: "standard" | "stripe" | "github" | "token";
628
+ header?: string;
629
+ idHeader?: string;
630
+ };
631
+ /** A deployed Listener as `ez listener list` shows it: never its secret. */
632
+ export type Listener = {
633
+ entry: ListenerEntry;
634
+ /** The address to give the sending service. */
635
+ url: string;
636
+ /** `rolling` while a replaced secret still verifies. */
637
+ secret: "none" | "set" | "rolling";
638
+ pending: number;
639
+ dead: number;
640
+ /** Refusals since the Host started, counted in memory, never stored. */
641
+ refused: {
642
+ signature: number;
643
+ timestamp: number;
644
+ noSecret: number;
645
+ size: number;
646
+ lastAt: number | null;
647
+ };
648
+ lastOkAt: number | null;
649
+ lastFailedAt: number | null;
650
+ lastFailure: string | null;
651
+ };
652
+ /** One delivery in a Listener's inbox; `body` only when shown. */
653
+ export type ListenerEvent = {
654
+ id: string;
655
+ deliveryId: string | null;
656
+ receivedAt: number;
657
+ attempt: number;
658
+ state: "pending" | "running" | "done" | "dead";
659
+ nextAt: number | null;
660
+ lastError: string | null;
661
+ /** The deployed function artifact that last ran it. */
662
+ version: string | null;
663
+ body?: string;
664
+ };
665
+ /**
666
+ * An API Key as `ez key list` shows it (docs/adr/0119): never the key, only its first characters. `actor` is
667
+ * what History records its writes as.
668
+ */
669
+ export type ApiKey = {
670
+ name: string;
671
+ actor: string;
672
+ prefix: string;
673
+ groups: string[];
674
+ createdBy: string;
675
+ createdAt: number;
676
+ expiresAt: number;
677
+ lastUsedAt: number | null;
678
+ revokedAt: number | null;
679
+ state: "active" | "expired" | "revoked";
680
+ };
681
+ export type ApiKeyInput = { name: string; groups?: string[]; expiresInDays?: number };
682
+ /** A new API Key: `key` is shown this once and never stored. `url` is the Site API's door. */
683
+ export type CreatedApiKey = { apiKey: ApiKey; key: string; url: string };
684
+ /** One global/schedules.json entry (ADRs 0076, 0136): run `global/jobs/<job>.ts` with `input` on a UTC `cron`. */
685
+ export type ScheduleEntry = {
686
+ name: string;
687
+ cron: string;
688
+ job: string;
689
+ input: Record<string, unknown>;
690
+ };
691
+ /**
692
+ * One of the Instance's schedules (ADRs 0076, 0136): its entry, when it last changed or was resumed, its next
693
+ * due time by its cron, its latest run, and when and by whom it was paused, or null (ADR 0120).
694
+ */
695
+ export type Schedule = ScheduleEntry & {
696
+ since: number;
697
+ next: number;
698
+ last: ScheduleRun | null;
699
+ paused: { at: number; by: string } | null;
700
+ };
701
+ /** What a scheduled job's context carries as `run` (ADR 0076); `due` is ISO, UTC. */
702
+ export type JobRun = { schedule: string; due: string; trigger: "schedule" | "manual" };
703
+ /** One run of a schedule: `due` and the times are ms since the epoch. */
704
+ export type ScheduleRun = {
705
+ id: string;
706
+ schedule: string;
707
+ due: number;
708
+ trigger: "schedule" | "manual";
709
+ status: "running" | "ok" | "error" | "refused" | "interrupted";
710
+ error: string | null;
711
+ startedAt: number;
712
+ finishedAt: number | null;
713
+ };
714
+ /**
715
+ * What ezship Desktop's preload exposes as `window.ezDesktop` (ADR 0048); absent in a browser. `call` runs
716
+ * one local function of the Site under `prefix` from the artifact with that build id and answers its result.
717
+ */
718
+ /** What the Desktop hands a local function (ADR 0048): the Member, the Site and this computer's folder for it. */
719
+ export type LocalContext = {
720
+ user: Readonly<{ id: string; email: string; name: string | null }>;
721
+ site: Readonly<{ instance: string; id: string; prefix: string }>;
722
+ desktop: Readonly<{ version: string; dataDir: string }>;
723
+ };
724
+ /** One published Desktop release file (ADR 0048), as the operator API lists it. */
725
+ export type DesktopFile = {
726
+ filename: string;
727
+ contentType: string;
728
+ size: number;
729
+ uploadedAt: number;
730
+ };
731
+ export type DesktopBridge = {
732
+ version: string;
733
+ call(prefix: string, artifact: string, name: string, input: unknown): Promise<unknown>;
734
+ };
735
+ /** Private build output (docs/adr/0105): every Global Document of the build's snapshot, compiled for QuickJS. */
736
+ export type DocumentArtifact = { id: string; names: string[]; code: string };
737
+ /** One element of a rendered Document, as the template stage returns it and the renderer reads it. */
738
+ export type DocumentNode = { t: string; p: Record<string, unknown>; c: (DocumentNode | string)[] };
739
+ export type RenderStatus = "queued" | "rendering" | "ready" | "failed";
740
+ /** The FILE column a finished Render binds its Document File to. */
741
+ export type RenderTarget = { table: string; id: string; column: string };
742
+ export type RenderOptions = { filename?: string; attachTo?: RenderTarget };
743
+ /** `renderDocument`: in a Site a queued Render; with `files` (the Global Working Copy) an immediate one. */
744
+ export type RenderRequest = RenderOptions & {
745
+ document: string;
746
+ input?: unknown;
747
+ /** Render the Document's own `example` input instead of `input`. */
748
+ example?: boolean;
749
+ preview?: string;
750
+ files?: Record<string, string>;
751
+ };
752
+ /** A Render (docs/adr/0105). `file` is its Document File's id once ready; `url` its app-host path. */
753
+ export type RenderRow = {
754
+ id: string;
755
+ site: string;
756
+ document: string;
757
+ origin: "page" | "function" | "builder";
758
+ requestedBy: string;
759
+ status: RenderStatus;
760
+ error: string | null;
761
+ file: string | null;
762
+ url: string | null;
763
+ filename: string;
764
+ target: RenderTarget | null;
765
+ attempts: number;
766
+ createdAt: number;
767
+ finishedAt: number | null;
768
+ };
769
+ /**
770
+ * An Email (docs/adr/0149): `queued` until the runner hands it on, `sending` while it does; `sent` (the mail
771
+ * service accepted it) and `logged` (a Host whose transport is the log) are delivered; `failed` was refused or
772
+ * never delivered within a day; `uncertain` was handed on but its answer was lost, and is never retried;
773
+ * `dropped` was never sent, `reason` says why.
774
+ */
775
+ export type EmailStatus =
776
+ | "queued"
777
+ | "sending"
778
+ | "sent"
779
+ | "logged"
780
+ | "failed"
781
+ | "uncertain"
782
+ | "dropped";
783
+ /**
784
+ * One Email as Builders list it. `site` is the sending Site or `global` (a job); `sender` the entry, such as
785
+ * `functions/notify` or `jobs/digest`; `member` the recipient's MEMBER value when they are a Member.
786
+ */
787
+ export type EmailRow = {
788
+ id: string;
789
+ site: string;
790
+ preview: boolean;
791
+ sender: string;
792
+ member: string | null;
793
+ recipient: string;
794
+ subject: string;
795
+ status: EmailStatus;
796
+ reason: string | null;
797
+ attempts: number;
798
+ createdAt: number;
799
+ finishedAt: number | null;
800
+ };
801
+ /** One Email with what it said: the Markdown body, its button, and the message as rendered. */
802
+ export type EmailInfo = EmailRow & {
803
+ body: string;
804
+ button: { label: string; href: string } | null;
805
+ text: string;
806
+ html: string;
807
+ };
808
+ /** `listEmails`: newest first, at most `limit` (default 50, at most 200), since an epoch-ms time. */
809
+ export type EmailFilter = { site?: string; status?: EmailStatus; since?: number; limit?: number };
810
+ /** What the Builder answers: errors (and warnings), or the Deployed Files with their manifest (empty for a check). */
811
+ export type BuildResult =
812
+ | { ok: false; diagnostics: Diagnostic[] }
813
+ | {
814
+ ok: true;
815
+ manifest: BuildManifest;
816
+ files: Record<string, string>;
817
+ /** Warnings (severity 2) the build passed with (docs/adr/0078); absent from older Builders. */
818
+ warnings?: Diagnostic[];
819
+ };
820
+
821
+ /** `ez format` (docs/adr/0089): the files whose text the formatter changed, or why it could not run. */
822
+ export type FormatResult = { files: Record<string, string>; diagnostics: Diagnostic[] };
823
+
824
+ /** A single-use initial password setup link, returned only to an Admin. */
825
+ /** Shared device authorization used by terminal and browser clients. */
826
+ export type DeviceStart = {
827
+ deviceCode: string;
828
+ userCode: string;
829
+ verificationUrl: string;
830
+ interval: number;
831
+ expiresAt: number;
832
+ };
833
+ export type DevicePoll = { status: "pending" | "expired" } | { status: "approved"; token: string };
834
+ /** Structured page reads; validated by the contract before any SQL is constructed. */
835
+ export type DataQuery = {
836
+ where?: Record<string, unknown>;
837
+ order?: string[];
838
+ limit?: number;
839
+ offset?: number;
840
+ /** false: past the active scope (docs/adr/0098). */
841
+ scope?: false;
842
+ };
843
+ export type AggregateQuery = {
844
+ where?: Record<string, unknown>;
845
+ group?: string[];
846
+ sum?: string[];
847
+ limit?: number;
848
+ offset?: number;
849
+ scope?: false;
850
+ };
851
+ export type AggregateRow = {
852
+ group: Record<string, string | number | boolean | null>;
853
+ count: number;
854
+ sum: Record<string, number>;
855
+ };
856
+ export type DataResult<R = Record<string, unknown>> = {
857
+ rows: R[];
858
+ version: number;
859
+ truncated: boolean;
860
+ /**
861
+ * The version of every Table the query read (docs/adr/0102): its own, the ones it included and those its
862
+ * where went through. A live query reruns when any of them moves.
863
+ */
864
+ versions?: Record<string, number>;
865
+ /** Some row's reverse include held more children than it brought (docs/adr/0102). */
866
+ truncatedChildren?: true;
867
+ };
868
+ /**
869
+ * The viewer's Session State (docs/adr/0088): what `GET <prefix>/_ez/session` answers and the page config
870
+ * carries. `values` holds only what the viewer stored and the declaration still accepts; defaults fill the rest.
871
+ */
872
+ export type SessionState = { values: Record<string, unknown>; version: number };
873
+ export type ActorRow = {
874
+ id: string;
875
+ /** Listeners and schedules (docs/adr/0092, 0136) write as `listener:<site>/<name>`, `schedule:<name>`. */
876
+ kind: "builder" | "user" | "listener" | "schedule";
877
+ name: string;
878
+ email: string;
879
+ };