@vercel/board 0.0.0 → 0.15.0

package/dist/contract-CuJmlrhw.mjs

@@ -0,0 +1,566 @@
+import { S as storable, _ as RemoteWatcherId, c as ChannelPath, d as LabelKey, g as MessageText, h as MessageId, i as Attachment, l as Emoji, m as MESSAGE_TEXT_MAX, n as ActorId, o as Author, p as Labels, u as Handle, v as SCOPE_MAX, y as SeenActorKind } from "./schemas-Be08nyfW.mjs";
+import { z } from "zod";
+import { contract } from "experimental-a2";
+//#region src/contract/contract.ts
+/**
+* An external thread or channel, prefixed with its sync key:
+* `slack:C0123ABC` (a channel), `slack:C0123ABC:1727.1234` (a thread),
+* `github:basehub-ai/www:12` (a PR thread).
+*/
+const ExternalTarget = z.string().min(3).max(300);
+/** Where a message came from on a platform. `thread` is grouped (GitHub review threads fold into their PR). */
+const Origin = z.object({
+	channel: ExternalTarget.optional(),
+	thread: ExternalTarget,
+	/** The exact platform thread, when it differs from `thread`. */
+	subthread: ExternalTarget.nullable(),
+	message: z.string().min(1).max(300),
+	context: z.string().max(300).nullable()
+});
+/** What a linked message said, as the board saw it when the link arrived. */
+const LinkSnapshot = z.object({
+	author: z.string().min(1).max(256),
+	text: z.string().max(MESSAGE_TEXT_MAX),
+	/** When it was written, if the platform said. */
+	createdAt: z.string().max(64).nullable(),
+	/** Its files, linked rather than copied. */
+	files: z.array(z.object({
+		name: z.string().min(1).max(1e3),
+		url: z.string().max(4e3).nullable()
+	})).max(20)
+});
+/**
+* A platform message linked from a message (a Slack permalink): the board message
+* it was synced to, if any, and a snapshot of it, or why the board couldn't read it.
+*/
+const Link = z.object({
+	url: z.string().min(1).max(4e3),
+	message: MessageId.nullable(),
+	snapshot: LinkSnapshot.nullable(),
+	/** Why there's no snapshot: `not_in_channel`, `channel_not_found`. */
+	unavailable: z.string().max(300).nullable()
+});
+/** The sync key a write came from, or null when it was written on the board. */
+const From = z.string().nullable();
+/** The thread key: the event ID of the thread's root. Lanes and sync state are keyed by it. */
+const ThreadKey = z.string().min(1).max(200).refine(storable, "thread key has a NUL character or a lone surrogate");
+/** The board's one log. Every board fact is an event in session `board`. */
+const boardContract = contract({
+	name: "board",
+	events: {
+		"message.posted": z.object({
+			channel: ChannelPath,
+			/** Empty only when the message has attachments. */
+			text: z.union([MessageText, z.literal("")]),
+			/** The thread root, or null for a root. */
+			re: MessageId.nullable(),
+			/** The exact message replied to, when it isn't the root. */
+			replyTo: MessageId.nullable(),
+			thread: ThreadKey,
+			labels: Labels,
+			noSync: z.boolean(),
+			mentions: z.array(ActorId),
+			by: Author,
+			origin: Origin.nullable(),
+			from: From,
+			/** Files on the message. Events written before attachments have none. */
+			attachments: z.array(Attachment).max(10).optional(),
+			/** Platform messages it links to. Events written before links have none. */
+			links: z.array(Link).max(10).optional(),
+			/** (server) Posted by a schedule: its ID and which send this is, from 0. Other messages have none. */
+			schedule: z.object({
+				id: z.number().int().positive(),
+				n: z.number().int().nonnegative()
+			}).optional(),
+			/**
+			* (server) Its author couldn't read the channel it posted in. Where a
+			* caller can't read, it edits and deletes only these of its own. Events
+			* from before channel access have none: everyone read everything then.
+			*/
+			blind: z.literal(true).optional(),
+			/**
+			* (server) The principal of the sync elsewhere that imported it, whose copy `origin` names:
+			* that sync's to act on. None for the board's own sync, or a write on the board.
+			*/
+			importedBy: ActorId.optional()
+		}),
+		/** A message's links changed: an edit linked something new, or the platform sent what a link says. */
+		"message.linked": z.object({
+			id: MessageId,
+			thread: ThreadKey,
+			links: z.array(Link).max(10),
+			by: Author,
+			from: From
+		}),
+		"message.edited": z.object({
+			id: MessageId,
+			thread: ThreadKey,
+			text: MessageText,
+			mentions: z.array(ActorId),
+			by: Author,
+			from: From
+		}),
+		"message.deleted": z.object({
+			id: MessageId,
+			thread: ThreadKey,
+			by: Author,
+			from: From
+		}),
+		"reaction.added": z.object({
+			id: MessageId,
+			thread: ThreadKey,
+			emoji: Emoji,
+			by: Author,
+			from: From
+		}),
+		"reaction.removed": z.object({
+			id: MessageId,
+			thread: ThreadKey,
+			emoji: Emoji,
+			by: Author,
+			from: From
+		}),
+		"labels.changed": z.object({
+			id: MessageId,
+			thread: ThreadKey,
+			set: Labels,
+			unset: z.array(LabelKey),
+			by: Author
+		}),
+		/** A thread is synced with an external channel (start a thread there) or thread (join it). */
+		"thread.synced": z.object({
+			thread: ThreadKey,
+			target: ExternalTarget,
+			cause: z.enum(["config", "request"]),
+			kind: z.enum(["channel", "thread"]).optional(),
+			by: Author
+		}),
+		/** An outbound delivery receipt: board message `id` exists on the platform as `external`. */
+		"message.synced": z.object({
+			id: MessageId,
+			thread: ThreadKey,
+			target: ExternalTarget,
+			external: z.object({
+				thread: ExternalTarget,
+				message: z.string().min(1).max(300),
+				/** Posted with its author's own platform token, so it shows as them. Older receipts have none. */
+				asUser: z.literal(true).optional()
+			}),
+			/**
+			* (server) The principal of the sync elsewhere that recorded it: its copy is that sync's to
+			* change. None for the board's own sync.
+			*/
+			syncedBy: ActorId.optional()
+		}),
+		/**
+		* Board message `id`'s files reached `target` after its text: `files` are the
+		* platform's IDs for them, or null when the platform refused files and the
+		* text got a line for each instead.
+		*/
+		"message.files_synced": z.object({
+			id: MessageId,
+			thread: ThreadKey,
+			target: ExternalTarget,
+			files: z.array(z.string().min(1).max(300)).max(10).nullable(),
+			/** (server) As on `message.synced`: only the sync that recorded the copy sets its files. */
+			syncedBy: ActorId.optional()
+		}),
+		/** A delivery that gave up: board message `id` didn't reach `target`, and `error` says why. */
+		"message.sync_failed": z.object({
+			id: MessageId,
+			thread: ThreadKey,
+			target: ExternalTarget,
+			error: z.string().min(1).max(500)
+		}),
+		"actor.seen": z.object({
+			actor: ActorId,
+			kind: SeenActorKind,
+			handle: Handle,
+			name: z.string().min(1).max(128).refine(storable, "name has a NUL character or a lone surrogate"),
+			avatar: z.string().url().nullable(),
+			/**
+			* (server) A principal a host's `authenticate` made, or one of its profiles: someone the board
+			* signs in, whatever its ID or kind, so sync never writes as it. Others have none.
+			*/
+			host: z.literal(true).optional()
+		}),
+		/**
+		* A platform actor (`slack:user:U0456`) is the same person as a principal
+		* (`vercel:user:…`): for display, `--by`, and mentions, never for permissions.
+		* `method` says how it was proved: a one-time code posted from that account,
+		* or the account's own sign-in (`consent`).
+		*/
+		"actor.linked": z.object({
+			actor: ActorId,
+			to: ActorId,
+			method: z.enum(["code", "consent"]),
+			by: Author
+		}),
+		"actor.unlinked": z.object({
+			actor: ActorId,
+			by: Author
+		})
+	}
+});
+const BOARD_SESSION = "board";
+const ExternalAuthor = z.object({
+	/** The platform principal, e.g. `slack:user:U0456`. */
+	id: z.string().min(1),
+	handle: z.string().min(1),
+	name: z.string().min(1),
+	avatar: z.string().nullable(),
+	isBot: z.boolean()
+});
+/**
+* A file on a platform message, as Chat SDK describes it: enough for the
+* platform's adapter to fetch it later (`rehydrateAttachment`), never the bytes.
+*/
+const ExternalFile = z.object({
+	type: z.enum([
+		"image",
+		"file",
+		"video",
+		"audio"
+	]),
+	name: z.string().max(1e3).optional(),
+	mimeType: z.string().max(255).optional(),
+	size: z.number().int().nonnegative().optional(),
+	url: z.string().max(4e3).optional(),
+	fetchMetadata: z.record(z.string(), z.string().max(4e3)).optional()
+});
+/**
+* A platform message a platform message links to, at intake: where it lives
+* (`thread`, with the sync key prefix, and `message`), and what it said when the
+* platform sent that along (Slack's unfurl).
+*/
+const ExternalLink = z.object({
+	url: z.string().min(1).max(4e3),
+	thread: ExternalTarget,
+	message: z.string().min(1).max(300),
+	snapshot: LinkSnapshot.nullable()
+});
+const ExternalLocation = z.object({
+	channel: ExternalTarget,
+	thread: ExternalTarget,
+	subthread: ExternalTarget.nullable()
+});
+/** A platform event, normalized at intake. Thread IDs are external IDs with the sync key prefix. */
+const ExternalEvent = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("message"),
+		...ExternalLocation.shape,
+		message: z.string(),
+		isRoot: z.boolean(),
+		text: z.string(),
+		context: z.string().nullable(),
+		author: ExternalAuthor,
+		/** Files on the message, fetched when it lands on the board. Older events have none. */
+		files: z.array(ExternalFile).max(20).optional(),
+		/** Platform messages it links to. Older events have none. */
+		links: z.array(ExternalLink).max(10).optional()
+	}),
+	z.object({
+		kind: z.literal("edited"),
+		...ExternalLocation.shape,
+		message: z.string(),
+		text: z.string(),
+		author: ExternalAuthor,
+		links: z.array(ExternalLink).max(10).optional(),
+		/** Only the links changed (the platform sent what they say), so `text` isn't news. */
+		linksOnly: z.boolean().optional()
+	}),
+	z.object({
+		kind: z.literal("deleted"),
+		...ExternalLocation.shape,
+		message: z.string()
+	}),
+	z.object({
+		kind: z.literal("reaction"),
+		...ExternalLocation.shape,
+		message: z.string(),
+		emoji: z.string(),
+		added: z.boolean(),
+		author: ExternalAuthor
+	}),
+	z.object({
+		/** A platform lifecycle event: a PR opening, closing, being reviewed. */
+		kind: z.literal("lifecycle"),
+		...ExternalLocation.omit({ subthread: true }).shape,
+		type: z.string(),
+		title: z.string(),
+		url: z.string().nullable(),
+		labels: z.record(z.string(), z.string()),
+		unset: z.array(z.string()),
+		/** Key prefixes the platform owns on the root, e.g. `tag.`: keys under them that aren't in `labels` are unset. */
+		owns: z.array(z.string()).optional(),
+		/** A reply to add to the thread, e.g. "merged by julian". */
+		reply: z.string().nullable(),
+		/** Create the root if the board hasn't seen this thread. */
+		createRoot: z.boolean(),
+		author: ExternalAuthor
+	})
+]);
+/** Raw platform events live outside the board log, one session per external channel. */
+const inboxContract = contract({
+	name: "board-inbox",
+	events: {
+		"external.received": z.object({
+			sync: z.string().min(1),
+			event: ExternalEvent,
+			raw: z.unknown()
+		}),
+		/** An inbox got its first event: session `inboxes` lists them, so a sync key's inbox lists every channel's. */
+		"inbox.opened": z.object({ channel: ExternalTarget })
+	}
+});
+/** `inbox:slack:C0123ABC`: the inbox session for one external channel. */
+const inboxSession = (channel) => `inbox:${channel}`;
+/** The session that lists the inboxes: one `inbox.opened` each. */
+const INBOXES_SESSION = "inboxes";
+/** What watchers matched, outside the board log: one session per watcher, so each fails on its own. */
+const MatchId = z.string().min(1).max(200);
+const LeaseId = z.string().min(1).max(64);
+/** What a queue keeps in order: a board thread's key, or a platform thread for an inbox. */
+const QueueLane = z.string().min(1).max(300).refine(storable, "lane has a NUL character or a lone surrogate");
+const watchContract = contract({
+	name: "board-watch",
+	events: {
+		"watch.matched": z.object({
+			/** The board thread, or for an inbox the platform thread: each one's matches go one at a time. */
+			thread: QueueLane,
+			/** The board event, as `vb tail --json` prints it, as the watcher may see it, or a platform event for an inbox. */
+			event: z.unknown(),
+			/** A registered watcher's ID: its registrant's session holds all of its watchers' matches. */
+			watcher: RemoteWatcherId.optional(),
+			/** The registrant's sync, which gets every event it delivers to platforms. */
+			sync: z.literal(true).optional(),
+			/** A platform event the registrant pushed to its inbox for this sync key, to pull back and import. */
+			inbox: z.string().min(1).max(64).optional()
+		}),
+		/** The watcher gave up on one match: `run` kept failing, and the thread's later events go on without it. */
+		"watch.failed": z.object({
+			/** The `watch.matched` event's ID. */
+			matched: MatchId,
+			thread: QueueLane,
+			error: z.string().min(1).max(500)
+		}),
+		/** A registrant pulled a match: it's theirs to run until `until`, or until they ack it. */
+		"watch.leased": z.object({
+			matched: MatchId,
+			lease: LeaseId,
+			until: z.number().int().nonnegative()
+		}),
+		/** The registrant ran it: done, or an error to try again after `retryAt`. A stale lease's ack changes nothing. */
+		"watch.acked": z.object({
+			matched: MatchId,
+			lease: LeaseId,
+			error: z.string().min(1).max(500).optional(),
+			retryAt: z.number().int().nonnegative().optional()
+		}),
+		/** A lease ran out with no ack: a try that didn't finish. */
+		"watch.expired": z.object({
+			matched: MatchId,
+			lease: LeaseId
+		}),
+		/** A match's wait after an error is over: it can be pulled again. */
+		"watch.retry": z.object({ matched: MatchId }),
+		/** A match its registrant can't have anymore: it may not read it, or the watcher is gone. */
+		"watch.skipped": z.object({
+			matched: MatchId,
+			reason: z.string().min(1).max(200)
+		}),
+		/** A sweep is set for `at`: one timer for every lease that runs out before it, or a wake-up to try again. */
+		"watch.armed": z.object({ at: z.number().int().nonnegative() }),
+		/** A timer: an error's wait is over (`matched`), or a sweep (`sweep`). Its consumer decides what it still means. */
+		"watch.due": z.object({
+			matched: MatchId.optional(),
+			retry: z.boolean().optional(),
+			sweep: z.number().int().nonnegative().optional()
+		}),
+		/** A wake-up didn't get there, `failures` in a row: nothing wakes the registrant again before `until`. */
+		"watch.unreachable": z.object({
+			failures: z.number().int().positive(),
+			until: z.number().int().nonnegative(),
+			/** Its answer's status, or the error. */
+			why: z.string().min(1).max(200)
+		}),
+		/** The registrant's board answered a wake-up, pulled, or registered: its next match wakes it. */
+		"watch.reachable": z.object({ by: z.enum([
+			"wake",
+			"pull",
+			"registration"
+		]) })
+	}
+});
+/** `watch:triage`: the session for one watcher, or `watch:@<principal>` for everything a registrant registered. */
+const watchSession = (id) => `watch:${id}`;
+/**
+* A principal as the board keeps it, to work out its access again later under
+* the rules as they are then: who it is, and the token facts rules match on.
+*/
+const StoredPrincipal = z.object({
+	id: z.string().min(1),
+	kind: z.enum([
+		"person",
+		"deployment",
+		"workflow",
+		"external"
+	]),
+	handle: Handle,
+	facts: z.object({
+		issuer: z.enum([
+			"vercel",
+			"github",
+			"oidc",
+			"host"
+		]),
+		iss: z.string().max(1e3),
+		claims: z.record(z.string(), z.union([
+			z.string().max(1e3),
+			z.number(),
+			z.boolean()
+		])),
+		/** The board's own Vercel team, as the board knew it when it verified the token. */
+		team: z.string().max(200).optional()
+	}).optional(),
+	scope: z.string().max(SCOPE_MAX).optional()
+});
+/** A watcher as a board on `http()` registers it: its tail, and when it runs. */
+const WatcherSpec = z.object({
+	tail: z.string().max(1e3),
+	when: z.enum(["matches", "enters"])
+});
+/**
+* Watchers that boards on `http()` registered with this one, outside the board
+* log: one session, `registry`. Each principal has one registration, and its
+* newest replaces the last.
+*/
+const registryContract = contract({
+	name: "board-registry",
+	events: { "watchers.registered": z.object({
+		/** The principal that registered, which its watchers' writes are by, with their IDs as profiles. */
+		owner: z.string().min(1).max(200),
+		/** It, to work out what it may read at each match: a watcher sees only what its registrant can. */
+		principal: StoredPrincipal,
+		/** Where to wake it: `<url>/wake`. Without one, it pulls on its own. */
+		url: z.string().url().max(500).nullable(),
+		watch: z.record(RemoteWatcherId, WatcherSpec),
+		/** Its sync entries: with any, its sync subscribes too, to every post, change, and thread sync where it may sync. Older registrations have none. */
+		sync: z.array(z.object({
+			key: z.string().min(1).max(64),
+			platform: z.string().min(1).max(64),
+			signIn: z.boolean()
+		})).max(32).optional(),
+		/** `watchersHash(watch)`, which every wake-up carries so the board can tell it's stale. */
+		hash: z.string().min(1).max(100)
+	}) }
+});
+const REGISTRY_SESSION = "registry";
+/** Epoch milliseconds. */
+const Millis = z.number().int().nonnegative();
+/**
+* Who a schedule posts as: the identity that created it, as the board resolved
+* it then. A token's verified claims (`facts`) and the scope it was narrowed by
+* let each send work out its access again, under the rules as they are then.
+* Schedules from before they were kept have neither.
+*/
+const ScheduleIdentity = z.object({
+	author: Author,
+	principal: StoredPrincipal,
+	actor: z.object({
+		id: ActorId,
+		kind: SeenActorKind,
+		handle: Handle,
+		name: z.string().min(1).max(128),
+		avatar: z.string().nullable()
+	})
+});
+/**
+* Scheduled messages, outside the board log: one session, `schedules`. A schedule's ID is
+* its `schedule.created` index. Each send is an A2 timer carrying `schedule.due`; timers
+* can't be revoked, so a canceled or superseded one fires into a no-op.
+*/
+const schedulesContract = contract({
+	name: "board-schedules",
+	events: {
+		"schedule.created": z.object({
+			/** A new root in `channel`, or a reply in the thread rooted at `re`. */
+			channel: ChannelPath,
+			re: MessageId.nullable(),
+			text: z.union([MessageText, z.literal("")]),
+			labels: Labels,
+			noSync: z.boolean(),
+			attachments: z.array(Attachment).max(10).optional(),
+			/** The first send. */
+			first: Millis,
+			/** Repeats this often after the first send, or null for once. */
+			every: Millis.nullable(),
+			/** Stops repeating after this time, or after this many sends. Null: never. */
+			until: Millis.nullable(),
+			times: z.number().int().positive().nullable(),
+			as: ScheduleIdentity,
+			/**
+			* (server) Its creator couldn't read its channel. Where a caller can't
+			* read, it sees and cancels only these of its own. Schedules from before
+			* channel access have none.
+			*/
+			blind: z.literal(true).optional()
+		}),
+		"schedule.canceled": z.object({
+			id: z.number().int().positive(),
+			by: Author,
+			/**
+			* `canceled`: someone canceled it; `thread_deleted`: the thread it replies in is gone;
+			* `dropped`: the board's middleware dropped a send, so it would drop the rest;
+			* `revoked`: its creator can no longer post there.
+			*/
+			reason: z.enum([
+				"canceled",
+				"thread_deleted",
+				"dropped",
+				"revoked"
+			])
+		}),
+		/** (server) A timer: send `n` is due at `at`. */
+		"schedule.due": z.object({
+			id: z.number().int().positive(),
+			n: z.number().int().nonnegative(),
+			at: Millis
+		}),
+		/** (server) Send `n` was posted as `message`; the next is due at `next`, or never. */
+		"schedule.fired": z.object({
+			id: z.number().int().positive(),
+			n: z.number().int().nonnegative(),
+			message: MessageId,
+			next: Millis.nullable()
+		})
+	}
+});
+const SCHEDULES_SESSION = "schedules";
+/**
+* One-time codes for linking accounts, outside the board log: a code is a secret
+* until it's used, and only its hash is kept. Session `identity`.
+*/
+const identityContract = contract({
+	name: "board-identity",
+	events: {
+		"identity.code_issued": z.object({
+			hash: z.string().min(1).max(128),
+			/** Who the account it's posted from links to. */
+			principal: ActorId,
+			/** The sync entry it must be posted through. */
+			sync: z.string().min(1).max(64),
+			expiresAt: z.string().max(64)
+		}),
+		/** The first account to post it wins; any later post is just a message. */
+		"identity.code_used": z.object({
+			hash: z.string().min(1).max(128),
+			actor: ActorId,
+			/** The message that used it (`externalMessageKey`): only a retry of that one claims it again. */
+			message: z.string().max(1024).optional()
+		})
+	}
+});
+const IDENTITY_SESSION = "identity";
+//#endregion
+export { schedulesContract as _, ExternalTarget as a, Link as c, SCHEDULES_SESSION as d, boardContract as f, registryContract as g, inboxSession as h, ExternalLocation as i, Origin as l, inboxContract as m, ExternalAuthor as n, IDENTITY_SESSION as o, identityContract as p, ExternalEvent as r, INBOXES_SESSION as s, BOARD_SESSION as t, REGISTRY_SESSION as u, watchContract as v, watchSession as y };