@mostra/protocol 0.11.0 → 0.13.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/dist/actions.d.ts +11 -3
- package/dist/actions.d.ts.map +1 -1
- package/dist/actions.js.map +1 -1
- package/dist/browser.d.ts +1 -1
- package/dist/diagnostics/codes/index.d.ts +3 -2
- package/dist/diagnostics/codes/index.d.ts.map +1 -1
- package/dist/diagnostics/codes/index.js +3 -1
- package/dist/diagnostics/codes/index.js.map +1 -1
- package/dist/diagnostics/codes/remote.js +2 -2
- package/dist/diagnostics/codes/remote.js.map +1 -1
- package/dist/diagnostics/codes/team.d.ts +8 -0
- package/dist/diagnostics/codes/team.d.ts.map +1 -0
- package/dist/diagnostics/codes/team.js +44 -0
- package/dist/diagnostics/codes/team.js.map +1 -0
- package/dist/diagnostics/diagnostic.d.ts +1 -1
- package/dist/diagnostics/diagnostic.d.ts.map +1 -1
- package/dist/diagnostics/diagnostic.js +2 -1
- package/dist/diagnostics/diagnostic.js.map +1 -1
- package/dist/index.d.ts +13 -6
- package/dist/index.js +11 -4
- package/dist/interaction.d.ts +12 -3
- package/dist/interaction.d.ts.map +1 -1
- package/dist/interaction.js +15 -12
- package/dist/interaction.js.map +1 -1
- package/dist/manifest.d.ts +3 -0
- package/dist/manifest.d.ts.map +1 -1
- package/dist/manifest.js +5 -2
- package/dist/manifest.js.map +1 -1
- package/dist/methods/index.d.ts.map +1 -1
- package/dist/methods/index.js +10 -2
- package/dist/methods/index.js.map +1 -1
- package/dist/methods/port/trusted-controls-policy.d.ts +1 -1
- package/dist/methods/results/get.d.ts +3 -1
- package/dist/methods/results/get.d.ts.map +1 -1
- package/dist/methods/results/get.js +4 -3
- package/dist/methods/results/get.js.map +1 -1
- package/dist/methods/results/list.d.ts +33 -0
- package/dist/methods/results/list.d.ts.map +1 -0
- package/dist/methods/results/list.js +35 -0
- package/dist/methods/results/list.js.map +1 -0
- package/dist/methods/roster/add.d.ts +47 -0
- package/dist/methods/roster/add.d.ts.map +1 -0
- package/dist/methods/roster/add.js +46 -0
- package/dist/methods/roster/add.js.map +1 -0
- package/dist/methods/roster/get.d.ts +18 -0
- package/dist/methods/roster/get.d.ts.map +1 -0
- package/dist/methods/roster/get.js +22 -0
- package/dist/methods/roster/get.js.map +1 -0
- package/dist/methods/roster/remove.d.ts +28 -0
- package/dist/methods/roster/remove.d.ts.map +1 -0
- package/dist/methods/roster/remove.js +31 -0
- package/dist/methods/roster/remove.js.map +1 -0
- package/dist/methods/share/start.d.ts +15 -2
- package/dist/methods/share/start.d.ts.map +1 -1
- package/dist/methods/share/start.js +5 -1
- package/dist/methods/share/start.js.map +1 -1
- package/dist/methods/state/get.d.ts +1 -1
- package/dist/methods/state/patch.d.ts +1 -1
- package/dist/methods/view/url.d.ts +1 -1
- package/dist/methods/wait/wait.d.ts +1 -1
- package/dist/operator.d.ts +93 -11
- package/dist/operator.d.ts.map +1 -1
- package/dist/operator.js.map +1 -1
- package/dist/team-settings.d.ts +21 -0
- package/dist/team-settings.d.ts.map +1 -0
- package/dist/team-settings.js +27 -0
- package/dist/team-settings.js.map +1 -0
- package/dist/team.d.ts +221 -0
- package/dist/team.d.ts.map +1 -0
- package/dist/team.js +162 -0
- package/dist/team.js.map +1 -0
- package/dist/verify.d.ts +7 -0
- package/dist/verify.d.ts.map +1 -1
- package/dist/verify.js.map +1 -1
- package/dist/worker.d.ts +1 -1
- package/package.json +1 -1
- package/schemas/protocol.draft-07.json +802 -79
- package/schemas/protocol.schema.json +782 -91
- package/src/actions.ts +8 -4
- package/src/diagnostics/codes/index.ts +6 -2
- package/src/diagnostics/codes/remote.ts +2 -2
- package/src/diagnostics/codes/team.ts +53 -0
- package/src/diagnostics/diagnostic.ts +3 -1
- package/src/index.ts +47 -2
- package/src/interaction.ts +24 -5
- package/src/manifest.ts +5 -0
- package/src/methods/index.ts +8 -0
- package/src/methods/results/get.ts +3 -2
- package/src/methods/results/list.ts +61 -0
- package/src/methods/roster/add.ts +77 -0
- package/src/methods/roster/get.ts +30 -0
- package/src/methods/roster/remove.ts +49 -0
- package/src/methods/share/start.ts +23 -3
- package/src/operator.ts +83 -10
- package/src/team-settings.ts +38 -0
- package/src/team.ts +398 -0
- package/src/verify.ts +7 -0
package/src/operator.ts
CHANGED
|
@@ -53,8 +53,14 @@ export const OPERATOR_TIME_LIMITS: {
|
|
|
53
53
|
|
|
54
54
|
/**
|
|
55
55
|
* An operation `limits.check` judges. When the operator doesn't answer in time, `share`,
|
|
56
|
-
* `version.push`, `link` and authoring fail closed, and `view`, `submit
|
|
57
|
-
* so nothing a person typed is lost (D165
|
|
56
|
+
* `version.push`, `link` and authoring fail closed, and `view`, `submit`, draft writes and relayed
|
|
57
|
+
* actions (`run`, `run.wait`, `call`) proceed, so nothing a person typed or pressed is lost (D165
|
|
58
|
+
* item 9).
|
|
59
|
+
*
|
|
60
|
+
* - `run`: a relayed action run is about to be recorded (quantity 1). A request that joins a run
|
|
61
|
+
* already recorded (its key or client key) is never asked.
|
|
62
|
+
* - `run.wait`: that run would wait for its owner, who is away (quantity 1), asked after `run`.
|
|
63
|
+
* - `call`: a plain call is about to be relayed to the owner (quantity 1).
|
|
58
64
|
*/
|
|
59
65
|
export type LimitOperation =
|
|
60
66
|
| "share"
|
|
@@ -78,9 +84,15 @@ export interface LimitQuery {
|
|
|
78
84
|
readonly artifact?: string;
|
|
79
85
|
/** The artifact's hosted route, for operations on one (WP-30). */
|
|
80
86
|
readonly routeId?: string;
|
|
87
|
+
/**
|
|
88
|
+
* The version being pushed, on `version.push` and `storage` (MT-03): a push that takes several
|
|
89
|
+
* rounds (the owner uploads the files it was told are missing, then pushes again) asks about the
|
|
90
|
+
* same version each round, so an operator counting versions counts this ID once.
|
|
91
|
+
*/
|
|
92
|
+
readonly versionId?: string;
|
|
81
93
|
/** What is asked for. */
|
|
82
94
|
readonly operation: LimitOperation;
|
|
83
|
-
/** How much: bytes for `storage
|
|
95
|
+
/** How much: bytes for `storage`, else 1. */
|
|
84
96
|
readonly quantity?: number;
|
|
85
97
|
}
|
|
86
98
|
|
|
@@ -118,12 +130,19 @@ export const LimitAnswer: z.ZodType<LimitAnswer> = z.union([
|
|
|
118
130
|
|
|
119
131
|
// ── metering ────────────────────────────────────────────────────────────────────────────
|
|
120
132
|
|
|
121
|
-
/**
|
|
133
|
+
/**
|
|
134
|
+
* A counter's name (INTERFACES §18.6). `bytes.stored` sums the client bytes a home uploads in a
|
|
135
|
+
* window; `bytes.held` is a level, not a sum: the client bytes a home holds, each file once however
|
|
136
|
+
* many of its versions name it, sent in the window after it changes (so it falls to what is left,
|
|
137
|
+
* and to 0 once, when content is removed), and for every home holding anything at the first window
|
|
138
|
+
* after a server starts and once a day (MT-03). Keep the latest value per home.
|
|
139
|
+
*/
|
|
122
140
|
export type MeterName =
|
|
123
141
|
| "views"
|
|
124
142
|
| "submissions"
|
|
125
143
|
| "requests"
|
|
126
144
|
| "bytes.stored"
|
|
145
|
+
| "bytes.held"
|
|
127
146
|
| "bytes.egress"
|
|
128
147
|
| "relay.messages"
|
|
129
148
|
| "mcp.calls"
|
|
@@ -170,7 +189,10 @@ export interface MeterBatch {
|
|
|
170
189
|
|
|
171
190
|
/**
|
|
172
191
|
* Who an identity provider says signed in (INTERFACES §18.5). `facts` carries what a provider
|
|
173
|
-
* tells beyond that
|
|
192
|
+
* tells beyond that, for an operator's policy: the built-in GitHub adapter gives `login`, the
|
|
193
|
+
* account's age (`createdAt`) and its public counts (`publicRepos`, `publicGists`, `followers`, from
|
|
194
|
+
* the same lookup, MT-03); the OpenID Connect adapter gives the ID token's claims its configuration
|
|
195
|
+
* names (`claims`, such as a Google Workspace account's domain `hd`), each under its own name.
|
|
174
196
|
*/
|
|
175
197
|
export interface SignInIdentity {
|
|
176
198
|
/** The provider's ID (`IdentityProvider.id`). */
|
|
@@ -183,7 +205,7 @@ export interface SignInIdentity {
|
|
|
183
205
|
readonly emailVerified?: boolean;
|
|
184
206
|
/** The display name the provider gives. */
|
|
185
207
|
readonly name?: string;
|
|
186
|
-
/** What else the provider tells (an account's age as `createdAt
|
|
208
|
+
/** What else the provider tells (an account's age as `createdAt`, chosen claims). */
|
|
187
209
|
readonly facts?: Readonly<Record<string, unknown>>;
|
|
188
210
|
}
|
|
189
211
|
|
|
@@ -224,6 +246,15 @@ export interface IdentityProvider {
|
|
|
224
246
|
readonly id: string;
|
|
225
247
|
/** What the sign-in page calls it ("GitHub"). */
|
|
226
248
|
readonly label: string;
|
|
249
|
+
/**
|
|
250
|
+
* Whether the provider verifies the names it gives, and the label a hosted page's sender line
|
|
251
|
+
* shows for it ("verified with Acme"; 1 to 64 characters, shown as text). Absent: a person who
|
|
252
|
+
* signs in through it is shown "name not verified". The server records the label on the sign-in
|
|
253
|
+
* identity when the provider links or signs in that person, so renaming or retiring the provider
|
|
254
|
+
* later changes no name already verified (MT-03). The built-in providers verify, but for the
|
|
255
|
+
* development one.
|
|
256
|
+
*/
|
|
257
|
+
readonly verifies?: { readonly label: string };
|
|
227
258
|
/** Where to send the person: the provider's authorization URL with `state` and PKCE. */
|
|
228
259
|
authorize(state: string, pkce: SignInPkce, context: SignInContext): string | Promise<string>;
|
|
229
260
|
/**
|
|
@@ -374,7 +405,10 @@ export interface LinkPolicy extends Cacheable {
|
|
|
374
405
|
readonly interstitial?: { readonly kind: string; readonly message?: string };
|
|
375
406
|
/** The longest a link may live from when it was minted. */
|
|
376
407
|
readonly maxTtl?: string;
|
|
377
|
-
/**
|
|
408
|
+
/**
|
|
409
|
+
* A link without a view for this long expires: judged from its last view before the one being
|
|
410
|
+
* opened (or from its minting), so a fresh visit to an idle link is refused as well (MT-03).
|
|
411
|
+
*/
|
|
378
412
|
readonly idleExpiry?: string;
|
|
379
413
|
/** The line after "Your answer was sent.", as text. */
|
|
380
414
|
readonly afterSubmit?: string;
|
|
@@ -481,7 +515,9 @@ export type OperatorEventKind =
|
|
|
481
515
|
/**
|
|
482
516
|
* One outbound event, delivered at least once with a stable `eventId`. `payload`:
|
|
483
517
|
* `submission.accepted` carries the submission's `Results` (INTERFACES §8, the `Results` type of `@mostra/protocol`); `version.pushed`
|
|
484
|
-
* `{ versionId, number }`; `run.ended` `{ runId, action, status }`; `roster.completed`
|
|
518
|
+
* `{ versionId, number }`; `run.ended` `{ runId, action, status }`; `roster.completed`
|
|
519
|
+
* `{ round, respondents, submissions: { ref, submissionId }[] }`, when every expected respondent
|
|
520
|
+
* answered (D168).
|
|
485
521
|
* `label` is the route's label, so an operator running several servers behind one front learns
|
|
486
522
|
* which serves which label (WP-30).
|
|
487
523
|
*/
|
|
@@ -568,8 +604,45 @@ export interface OperatorPorts {
|
|
|
568
604
|
};
|
|
569
605
|
/** Outbound events, at least once with stable IDs. Default: discard. */
|
|
570
606
|
readonly events?: { deliver(e: OperatorEvent): Promise<void> };
|
|
571
|
-
/**
|
|
572
|
-
|
|
607
|
+
/**
|
|
608
|
+
* Invitations to expected respondents (D121, D168): for each respondent a hosted roster names
|
|
609
|
+
* with an `email`, when they are added or their personal link is replaced, so the operator can
|
|
610
|
+
* mail them their link. At least once, ordered per home, with a stable `invitationId`. No mailer
|
|
611
|
+
* ships: the open server only hands them over. Default: none sent.
|
|
612
|
+
*/
|
|
613
|
+
readonly invitations?: { send(invitation: Invitation): Promise<void> };
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
/**
|
|
617
|
+
* One invitation (D168). `url` is the respondent's personal link, a capability URL whose secret is
|
|
618
|
+
* in its fragment: the server never stores or logs it (it builds it from the link's token when it
|
|
619
|
+
* hands the invitation over), so the operator mails it and keeps it no longer than that.
|
|
620
|
+
*/
|
|
621
|
+
export interface Invitation {
|
|
622
|
+
/** Stable across retries: `<home>:<tokenId>`, one per personal link. */
|
|
623
|
+
readonly invitationId: string;
|
|
624
|
+
/** The account that owns the route. */
|
|
625
|
+
readonly account: string;
|
|
626
|
+
/** Its hosted home. */
|
|
627
|
+
readonly home: string;
|
|
628
|
+
/** The route. */
|
|
629
|
+
readonly routeId: string;
|
|
630
|
+
/** The route's label. */
|
|
631
|
+
readonly label: string;
|
|
632
|
+
/** The artifact's ID. */
|
|
633
|
+
readonly artifactId: string;
|
|
634
|
+
/** The artifact's title, as its latest version names it. */
|
|
635
|
+
readonly title: string;
|
|
636
|
+
/** Who is invited: the owner's key for them, their name and the address to write to. */
|
|
637
|
+
readonly respondent: { readonly ref: string; readonly name?: string; readonly email: string };
|
|
638
|
+
/** Who invites: the owner's display name and the provider that verified it, when one did. */
|
|
639
|
+
readonly sender: { readonly name?: string; readonly verifiedBy?: string };
|
|
640
|
+
/** The personal link. */
|
|
641
|
+
readonly url: string;
|
|
642
|
+
/** When the link stops working, when it has a lifetime. */
|
|
643
|
+
readonly expiresAt?: string;
|
|
644
|
+
/** When the respondent was added, or their link replaced. */
|
|
645
|
+
readonly at: string;
|
|
573
646
|
}
|
|
574
647
|
|
|
575
648
|
/** A hosted route, or one version of it: what the handle's quarantine and release act on. */
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The manifest's `team` settings (D168): a module of its own, with no other import of the
|
|
3
|
+
* protocol, so the manifest reads them without the team wire types.
|
|
4
|
+
*/
|
|
5
|
+
import * as z from "zod";
|
|
6
|
+
import { wireRegistry } from "./wire-registry.ts";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* What viewers see of each other's respondent status and presence (CO-07, D168): `private` (their
|
|
10
|
+
* own entry only), `counts` (their own entry and how many stand where), `names` (everyone's name and
|
|
11
|
+
* status). The manifest's `team.visibility`; owners, agents and hosts always see everything.
|
|
12
|
+
*/
|
|
13
|
+
export type TeamVisibility = "private" | "counts" | "names";
|
|
14
|
+
|
|
15
|
+
/** The Zod schema of the `TeamVisibility` type. */
|
|
16
|
+
export const TeamVisibility: z.ZodType<TeamVisibility> = z
|
|
17
|
+
.enum(["private", "counts", "names"])
|
|
18
|
+
.register(wireRegistry, {
|
|
19
|
+
id: "TeamVisibility",
|
|
20
|
+
description: "What viewers see of each other: private, counts or names (D168).",
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
/** The visibility an artifact gets when its manifest names none (D168: private unless it opts in). */
|
|
24
|
+
export const DEFAULT_TEAM_VISIBILITY: TeamVisibility = "private";
|
|
25
|
+
|
|
26
|
+
/** The manifest's `team` settings (D168). */
|
|
27
|
+
export interface TeamSettings {
|
|
28
|
+
/** What viewers see of each other's status and presence; default `private`. */
|
|
29
|
+
readonly visibility?: TeamVisibility;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** The Zod schema of the `TeamSettings` type. */
|
|
33
|
+
export const TeamSettings: z.ZodType<TeamSettings> = z
|
|
34
|
+
.object({ visibility: TeamVisibility.exactOptional() })
|
|
35
|
+
.register(wireRegistry, {
|
|
36
|
+
id: "TeamSettings",
|
|
37
|
+
description: "An artifact's team settings: what viewers see of each other (D168).",
|
|
38
|
+
});
|
package/src/team.ts
ADDED
|
@@ -0,0 +1,398 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Team features (D121, D168; INTERFACES §2.3, §4, §6): expected respondents and their roster,
|
|
3
|
+
* respondent status, the visibility policy, and presence. The host protocol's `roster/*` methods,
|
|
4
|
+
* the browser protocol's `respondents` and `presence` routes and the client hooks
|
|
5
|
+
* (`useRespondents`, `usePresence`) speak these shapes. Presence is never stored (D47): its shapes
|
|
6
|
+
* travel only as ephemeral messages and answers.
|
|
7
|
+
*/
|
|
8
|
+
import * as z from "zod";
|
|
9
|
+
import { SubmissionId, ViewerId, ViewId } from "./ids.ts";
|
|
10
|
+
import { ViewerKind } from "./interaction.ts";
|
|
11
|
+
import { DEFAULT_TEAM_VISIBILITY, TeamSettings, TeamVisibility } from "./team-settings.ts";
|
|
12
|
+
import { wireRegistry } from "./wire-registry.ts";
|
|
13
|
+
|
|
14
|
+
export { DEFAULT_TEAM_VISIBILITY, TeamSettings, TeamVisibility };
|
|
15
|
+
|
|
16
|
+
// ── Respondents ──────────────────────────────────────────────────────────────────────────────
|
|
17
|
+
|
|
18
|
+
/** The most expected respondents one artifact's roster holds. */
|
|
19
|
+
export const ROSTER_MAX = 1000;
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* An expected respondent as a host or agent names them (D121): the host's stable key for the
|
|
23
|
+
* person (`view/url`'s `viewer.ref`, D104), their display name, and an email address a remote
|
|
24
|
+
* server may send an invitation to (its operator's `invitations` port; nothing is sent locally).
|
|
25
|
+
*/
|
|
26
|
+
export interface RespondentSpec {
|
|
27
|
+
/** The host's stable key for this person, such as an email or an account ID (D104). */
|
|
28
|
+
readonly ref: string;
|
|
29
|
+
/** The name people see; updated when given again. */
|
|
30
|
+
readonly name?: string;
|
|
31
|
+
/** Where a remote server's operator may send this person's invitation. Never sent by Mostra. */
|
|
32
|
+
readonly email?: string;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** The Zod schema of the `RespondentSpec` type. */
|
|
36
|
+
export const RespondentSpec: z.ZodType<RespondentSpec> = z
|
|
37
|
+
.object({
|
|
38
|
+
ref: z.string().min(1).max(256),
|
|
39
|
+
name: z.string().min(1).max(256).exactOptional(),
|
|
40
|
+
email: z
|
|
41
|
+
.string()
|
|
42
|
+
.max(320)
|
|
43
|
+
.regex(/^[^\s@]+@[^\s@]+$/)
|
|
44
|
+
.exactOptional(),
|
|
45
|
+
})
|
|
46
|
+
.register(wireRegistry, {
|
|
47
|
+
id: "RespondentSpec",
|
|
48
|
+
description: "An expected respondent: the host's stable key, a display name, an email.",
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Where an expected respondent stands in the roster's current round (CO-03): `not-opened` (no view
|
|
53
|
+
* of the artifact since the round began), `drafting` (opened it or wrote their draft since), or
|
|
54
|
+
* `submitted` (a submission in the round). Open for later states on the wire.
|
|
55
|
+
*/
|
|
56
|
+
export type RespondentStatus = "not-opened" | "drafting" | "submitted";
|
|
57
|
+
|
|
58
|
+
/** The Zod schema of the `RespondentStatus` type. */
|
|
59
|
+
export const RespondentStatus: z.ZodType<RespondentStatus> = z
|
|
60
|
+
.enum(["not-opened", "drafting", "submitted"])
|
|
61
|
+
.register(wireRegistry, {
|
|
62
|
+
id: "RespondentStatus",
|
|
63
|
+
description: "Where a respondent stands in the round: not-opened, drafting or submitted.",
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
/** How many respondents stand where, in the current round. */
|
|
67
|
+
export interface RosterCounts {
|
|
68
|
+
/** Every expected respondent. */
|
|
69
|
+
readonly total: number;
|
|
70
|
+
/** How many haven't opened the artifact in the round. */
|
|
71
|
+
readonly notOpened: number;
|
|
72
|
+
/** How many opened it or wrote their draft in the round, without submitting. */
|
|
73
|
+
readonly drafting: number;
|
|
74
|
+
/** How many submitted in the round. */
|
|
75
|
+
readonly submitted: number;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** The Zod schema of the `RosterCounts` type. */
|
|
79
|
+
export const RosterCounts: z.ZodType<RosterCounts> = z
|
|
80
|
+
.object({
|
|
81
|
+
total: z.int().min(0),
|
|
82
|
+
notOpened: z.int().min(0),
|
|
83
|
+
drafting: z.int().min(0),
|
|
84
|
+
submitted: z.int().min(0),
|
|
85
|
+
})
|
|
86
|
+
.register(wireRegistry, {
|
|
87
|
+
id: "RosterCounts",
|
|
88
|
+
description: "How many respondents have not opened, are drafting, or submitted in the round.",
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
/** One expected respondent as agents and hosts read it (`roster/get`): everything. */
|
|
92
|
+
export interface Respondent {
|
|
93
|
+
/** The host's stable key for the person. */
|
|
94
|
+
readonly ref: string;
|
|
95
|
+
/** The display name. */
|
|
96
|
+
readonly name?: string;
|
|
97
|
+
/** The invitation address, when one was given. */
|
|
98
|
+
readonly email?: string;
|
|
99
|
+
/** The viewer the person's personal link acts as (D104). */
|
|
100
|
+
readonly viewerId: string;
|
|
101
|
+
/** Where they stand in the current round. */
|
|
102
|
+
readonly status: RespondentStatus;
|
|
103
|
+
/** When they first opened the artifact. */
|
|
104
|
+
readonly openedAt?: string;
|
|
105
|
+
/** When they last opened it or wrote their draft. */
|
|
106
|
+
readonly activeAt?: string;
|
|
107
|
+
/** Their submission in the current round, when they made one. */
|
|
108
|
+
readonly submission?: { readonly id: string; readonly at: string };
|
|
109
|
+
/** How many submissions they made in all. */
|
|
110
|
+
readonly submissions: number;
|
|
111
|
+
/** Their personal link's token, for `view/rotate` and `view/revoke`; absent once revoked. */
|
|
112
|
+
readonly tokenId?: string;
|
|
113
|
+
/** When they joined the roster. */
|
|
114
|
+
readonly addedAt: string;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** The Zod schema of the `Respondent` type. */
|
|
118
|
+
export const Respondent: z.ZodType<Respondent> = z
|
|
119
|
+
.object({
|
|
120
|
+
ref: z.string(),
|
|
121
|
+
name: z.string().exactOptional(),
|
|
122
|
+
email: z.string().exactOptional(),
|
|
123
|
+
viewerId: ViewerId.schema,
|
|
124
|
+
status: RespondentStatus,
|
|
125
|
+
openedAt: z.iso.datetime().exactOptional(),
|
|
126
|
+
activeAt: z.iso.datetime().exactOptional(),
|
|
127
|
+
submission: z.object({ id: SubmissionId.schema, at: z.iso.datetime() }).exactOptional(),
|
|
128
|
+
submissions: z.int().min(0),
|
|
129
|
+
tokenId: z.string().exactOptional(),
|
|
130
|
+
addedAt: z.iso.datetime(),
|
|
131
|
+
})
|
|
132
|
+
.register(wireRegistry, {
|
|
133
|
+
id: "Respondent",
|
|
134
|
+
description:
|
|
135
|
+
"An expected respondent as agents and hosts read it: name, viewer, status and submission.",
|
|
136
|
+
});
|
|
137
|
+
|
|
138
|
+
/** An artifact's roster as agents and hosts read it (`roster/get`). */
|
|
139
|
+
export interface Roster {
|
|
140
|
+
/** The roster's round (D168): always 1 under `once`; under `epochs`, one more after each completion. */
|
|
141
|
+
readonly round: number;
|
|
142
|
+
/** Whether every expected respondent has submitted in the round; an empty roster never has. */
|
|
143
|
+
readonly complete: boolean;
|
|
144
|
+
/** What viewers see of each other (the manifest's `team.visibility`). */
|
|
145
|
+
readonly visibility: TeamVisibility;
|
|
146
|
+
/** How many stand where in the round. */
|
|
147
|
+
readonly counts: RosterCounts;
|
|
148
|
+
/** Every expected respondent, in the order they joined. */
|
|
149
|
+
readonly respondents: readonly Respondent[];
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/** The Zod schema of the `Roster` type. */
|
|
153
|
+
export const Roster: z.ZodType<Roster> = z
|
|
154
|
+
.object({
|
|
155
|
+
round: z.int().min(1),
|
|
156
|
+
complete: z.boolean(),
|
|
157
|
+
visibility: TeamVisibility,
|
|
158
|
+
counts: RosterCounts,
|
|
159
|
+
respondents: z.array(Respondent).readonly(),
|
|
160
|
+
})
|
|
161
|
+
.register(wireRegistry, {
|
|
162
|
+
id: "Roster",
|
|
163
|
+
description: "An artifact's expected respondents with their status, the round and its counts.",
|
|
164
|
+
});
|
|
165
|
+
|
|
166
|
+
/**
|
|
167
|
+
* Another viewer as a page may see them: an opaque key that is stable for one viewer of one
|
|
168
|
+
* artifact (never a viewer or view ID, D104), their display name and how Mostra knows them.
|
|
169
|
+
*/
|
|
170
|
+
export interface Peer {
|
|
171
|
+
/** Stable for one viewer of one artifact, different across artifacts; `self` marks the page's own. */
|
|
172
|
+
readonly key: string;
|
|
173
|
+
/** Whether this is the page's own viewer. */
|
|
174
|
+
readonly self: boolean;
|
|
175
|
+
/** The display name, when one is known. */
|
|
176
|
+
readonly name?: string;
|
|
177
|
+
/** How Mostra knows the viewer. */
|
|
178
|
+
readonly kind: ViewerKind;
|
|
179
|
+
/** On a hosted link: whether a provider verified the name (D165 item 8). */
|
|
180
|
+
readonly verified?: boolean;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
const peerShape = {
|
|
184
|
+
key: z.string().min(1).max(64),
|
|
185
|
+
self: z.boolean(),
|
|
186
|
+
name: z.string().exactOptional(),
|
|
187
|
+
kind: ViewerKind,
|
|
188
|
+
verified: z.boolean().exactOptional(),
|
|
189
|
+
};
|
|
190
|
+
|
|
191
|
+
/** One respondent as a page sees them under the visibility policy. */
|
|
192
|
+
export interface RespondentForPage extends Peer {
|
|
193
|
+
/** Where they stand in the round. */
|
|
194
|
+
readonly status: RespondentStatus;
|
|
195
|
+
/** When they first opened the artifact. */
|
|
196
|
+
readonly openedAt?: string;
|
|
197
|
+
/** When they submitted in the round. */
|
|
198
|
+
readonly submittedAt?: string;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/** The Zod schema of the `RespondentForPage` type. */
|
|
202
|
+
export const RespondentForPage: z.ZodType<RespondentForPage> = z
|
|
203
|
+
.object({
|
|
204
|
+
...peerShape,
|
|
205
|
+
status: RespondentStatus,
|
|
206
|
+
openedAt: z.iso.datetime().exactOptional(),
|
|
207
|
+
submittedAt: z.iso.datetime().exactOptional(),
|
|
208
|
+
})
|
|
209
|
+
.register(wireRegistry, {
|
|
210
|
+
id: "RespondentForPage",
|
|
211
|
+
description: "A respondent as a page sees them: key, name, status, when opened and submitted.",
|
|
212
|
+
});
|
|
213
|
+
|
|
214
|
+
/**
|
|
215
|
+
* The roster as one page may see it (CO-03, CO-07): under `private` only the viewer's own entry,
|
|
216
|
+
* under `counts` also the counts and whether the round is complete, under `names` every respondent.
|
|
217
|
+
* The owner's page sees as under `names`.
|
|
218
|
+
*/
|
|
219
|
+
export interface RosterForPage {
|
|
220
|
+
/** The policy that decided what this answer holds. */
|
|
221
|
+
readonly visibility: TeamVisibility;
|
|
222
|
+
/** Whether this page's viewer sees everything as the artifact's owner. */
|
|
223
|
+
readonly owner: boolean;
|
|
224
|
+
/** The roster's round (always 1 under `once`). */
|
|
225
|
+
readonly round: number;
|
|
226
|
+
/** The viewer's own entry, when they are an expected respondent. */
|
|
227
|
+
readonly self?: RespondentForPage;
|
|
228
|
+
/** Under `counts` and `names`, and for the owner. */
|
|
229
|
+
readonly counts?: RosterCounts;
|
|
230
|
+
/** Under `counts` and `names`, and for the owner. */
|
|
231
|
+
readonly complete?: boolean;
|
|
232
|
+
/** Under `names`, and for the owner: every respondent, in the order they joined. */
|
|
233
|
+
readonly respondents?: readonly RespondentForPage[];
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/** The Zod schema of the `RosterForPage` type. */
|
|
237
|
+
export const RosterForPage: z.ZodType<RosterForPage> = z
|
|
238
|
+
.object({
|
|
239
|
+
visibility: TeamVisibility,
|
|
240
|
+
owner: z.boolean(),
|
|
241
|
+
round: z.int().min(1),
|
|
242
|
+
self: RespondentForPage.exactOptional(),
|
|
243
|
+
counts: RosterCounts.exactOptional(),
|
|
244
|
+
complete: z.boolean().exactOptional(),
|
|
245
|
+
respondents: z.array(RespondentForPage).readonly().exactOptional(),
|
|
246
|
+
})
|
|
247
|
+
.register(wireRegistry, {
|
|
248
|
+
id: "RosterForPage",
|
|
249
|
+
description: "The roster as a page may see it under the visibility policy (CO-07).",
|
|
250
|
+
});
|
|
251
|
+
|
|
252
|
+
/** `POST …/respondents`: reads the roster as the page may see it and follows it for a minute. */
|
|
253
|
+
export interface RespondentsRequest {
|
|
254
|
+
/** The view the page was opened as (D104). */
|
|
255
|
+
readonly viewId: string;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/** The Zod schema of the `RespondentsRequest` type. */
|
|
259
|
+
export const RespondentsRequest: z.ZodType<RespondentsRequest> = z
|
|
260
|
+
.object({ viewId: ViewId.schema })
|
|
261
|
+
.register(wireRegistry, {
|
|
262
|
+
id: "RespondentsRequest",
|
|
263
|
+
description: "Reads the roster as the page may see it, and follows it for a minute.",
|
|
264
|
+
});
|
|
265
|
+
|
|
266
|
+
// ── Presence ─────────────────────────────────────────────────────────────────────────────────
|
|
267
|
+
|
|
268
|
+
/** The largest coordinate a shared cursor may carry, in CSS pixels. */
|
|
269
|
+
export const PRESENCE_COORDINATE_MAX = 10_000_000;
|
|
270
|
+
|
|
271
|
+
/** A shared pointer position, in the page's document coordinates (CSS pixels). */
|
|
272
|
+
export interface PresenceCursor {
|
|
273
|
+
/** From the document's left edge. */
|
|
274
|
+
readonly x: number;
|
|
275
|
+
/** From the document's top edge. */
|
|
276
|
+
readonly y: number;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/** The Zod schema of the `PresenceCursor` type. */
|
|
280
|
+
export const PresenceCursor: z.ZodType<PresenceCursor> = z
|
|
281
|
+
.object({
|
|
282
|
+
x: z.number().min(-PRESENCE_COORDINATE_MAX).max(PRESENCE_COORDINATE_MAX),
|
|
283
|
+
y: z.number().min(-PRESENCE_COORDINATE_MAX).max(PRESENCE_COORDINATE_MAX),
|
|
284
|
+
})
|
|
285
|
+
.register(wireRegistry, {
|
|
286
|
+
id: "PresenceCursor",
|
|
287
|
+
description: "A shared pointer position in the page's document coordinates, in CSS pixels.",
|
|
288
|
+
});
|
|
289
|
+
|
|
290
|
+
/**
|
|
291
|
+
* A shared selection: the element the viewer is in (its `data-presence-id`, `id` or `name`) and,
|
|
292
|
+
* in a text input, the selected range.
|
|
293
|
+
*/
|
|
294
|
+
export interface PresenceSelection {
|
|
295
|
+
/** The element: its `data-presence-id`, `id` or `name`. */
|
|
296
|
+
readonly element?: string;
|
|
297
|
+
/** In a text input, where the selection starts. */
|
|
298
|
+
readonly start?: number;
|
|
299
|
+
/** In a text input, where it ends. */
|
|
300
|
+
readonly end?: number;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/** The Zod schema of the `PresenceSelection` type. */
|
|
304
|
+
export const PresenceSelection: z.ZodType<PresenceSelection> = z
|
|
305
|
+
.object({
|
|
306
|
+
element: z.string().min(1).max(256).exactOptional(),
|
|
307
|
+
start: z.int().min(0).max(PRESENCE_COORDINATE_MAX).exactOptional(),
|
|
308
|
+
end: z.int().min(0).max(PRESENCE_COORDINATE_MAX).exactOptional(),
|
|
309
|
+
})
|
|
310
|
+
.register(wireRegistry, {
|
|
311
|
+
id: "PresenceSelection",
|
|
312
|
+
description: "A shared selection: the element the viewer is in and the selected text range.",
|
|
313
|
+
});
|
|
314
|
+
|
|
315
|
+
/**
|
|
316
|
+
* `POST …/presence`: the page joins presence for the next half minute, sharing what it gives
|
|
317
|
+
* (CO-04). `cursor` and `selection` replace what the page shared (`null` stops sharing it); `leave`
|
|
318
|
+
* ends the page's presence at once. Never stored.
|
|
319
|
+
*/
|
|
320
|
+
export interface PresenceRequest {
|
|
321
|
+
/** The view the page was opened as (D104). */
|
|
322
|
+
readonly viewId: string;
|
|
323
|
+
/** The pointer to share; `null` stops sharing it; absent leaves it as it was. */
|
|
324
|
+
readonly cursor?: PresenceCursor | null;
|
|
325
|
+
/** The selection to share; `null` stops sharing it; absent leaves it as it was. */
|
|
326
|
+
readonly selection?: PresenceSelection | null;
|
|
327
|
+
/** Ends the page's presence now. */
|
|
328
|
+
readonly leave?: true;
|
|
329
|
+
/**
|
|
330
|
+
* The page's own count of its presence posts, growing with each (a leave included): a post the
|
|
331
|
+
* gateway gets after one with a higher count, such as an update that overtook the page's leave,
|
|
332
|
+
* changes nothing.
|
|
333
|
+
*/
|
|
334
|
+
readonly seq?: number;
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
/** The Zod schema of the `PresenceRequest` type. */
|
|
338
|
+
export const PresenceRequest: z.ZodType<PresenceRequest> = z
|
|
339
|
+
.object({
|
|
340
|
+
viewId: ViewId.schema,
|
|
341
|
+
cursor: PresenceCursor.nullable().exactOptional(),
|
|
342
|
+
selection: PresenceSelection.nullable().exactOptional(),
|
|
343
|
+
leave: z.literal(true).exactOptional(),
|
|
344
|
+
seq: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).exactOptional(),
|
|
345
|
+
})
|
|
346
|
+
.register(wireRegistry, {
|
|
347
|
+
id: "PresenceRequest",
|
|
348
|
+
description: "Joins presence for half a minute, sharing a cursor and a selection, or leaves.",
|
|
349
|
+
});
|
|
350
|
+
|
|
351
|
+
/** A viewer present on the artifact now, as a page may see them. */
|
|
352
|
+
export interface PresencePeer extends Peer {
|
|
353
|
+
/** Their pointer, when they share it. */
|
|
354
|
+
readonly cursor?: PresenceCursor;
|
|
355
|
+
/** Their selection, when they share it. */
|
|
356
|
+
readonly selection?: PresenceSelection;
|
|
357
|
+
/** When they last told Mostra anything. */
|
|
358
|
+
readonly at: string;
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
/** The Zod schema of the `PresencePeer` type. */
|
|
362
|
+
export const PresencePeer: z.ZodType<PresencePeer> = z
|
|
363
|
+
.object({
|
|
364
|
+
...peerShape,
|
|
365
|
+
cursor: PresenceCursor.exactOptional(),
|
|
366
|
+
selection: PresenceSelection.exactOptional(),
|
|
367
|
+
at: z.iso.datetime(),
|
|
368
|
+
})
|
|
369
|
+
.register(wireRegistry, {
|
|
370
|
+
id: "PresencePeer",
|
|
371
|
+
description: "A viewer present now: key, name, and the cursor and selection they share.",
|
|
372
|
+
});
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* Who is present, as one page may see it (CO-04, CO-07): under `names` (or for the owner) every
|
|
376
|
+
* present viewer with what they share; under `counts` how many others are present; under
|
|
377
|
+
* `private` only the page's own viewer.
|
|
378
|
+
*/
|
|
379
|
+
export interface PresenceState {
|
|
380
|
+
/** The policy that decided what this answer holds. */
|
|
381
|
+
readonly visibility: TeamVisibility;
|
|
382
|
+
/** Present viewers this page may see, its own first. */
|
|
383
|
+
readonly peers: readonly PresencePeer[];
|
|
384
|
+
/** How many other viewers are present, under `counts` and `names`. */
|
|
385
|
+
readonly others?: number;
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
/** The Zod schema of the `PresenceState` type. */
|
|
389
|
+
export const PresenceState: z.ZodType<PresenceState> = z
|
|
390
|
+
.object({
|
|
391
|
+
visibility: TeamVisibility,
|
|
392
|
+
peers: z.array(PresencePeer).readonly(),
|
|
393
|
+
others: z.int().min(0).exactOptional(),
|
|
394
|
+
})
|
|
395
|
+
.register(wireRegistry, {
|
|
396
|
+
id: "PresenceState",
|
|
397
|
+
description: "Who is present, as a page may see them under the visibility policy.",
|
|
398
|
+
});
|
package/src/verify.ts
CHANGED
|
@@ -403,6 +403,13 @@ export interface RenderResult {
|
|
|
403
403
|
readonly timedOut: boolean;
|
|
404
404
|
/** When each step ended, in ms after the render started. */
|
|
405
405
|
readonly timingsMs: Readonly<Record<string, number>>;
|
|
406
|
+
/**
|
|
407
|
+
* Why the page was rendered a second time, in a fresh browser context, when it was: a
|
|
408
|
+
* connection the browser couldn't make for a reason of its own (Chromium's random local port
|
|
409
|
+
* colliding on Windows, `net::ERR_NO_BUFFER_SPACE`, D157, #132). The second render's findings
|
|
410
|
+
* are the answer's.
|
|
411
|
+
*/
|
|
412
|
+
readonly renderedAgain?: string;
|
|
406
413
|
}
|
|
407
414
|
|
|
408
415
|
/** `verify/compare`'s params; internal to Mostra. */
|